@gramercytech/gx-componentkit/README.md

Vue 3 component library for building kiosk-style applications on the Eventfinity platform

# Gx ComponentKit

A Vue 3 component library for building kiosk-style applications on the Eventfinity platform.

## Overview

Gx ComponentKit provides a comprehensive set of Vue 3 components and composables designed specifically for creating interactive kiosk applications. It includes everything you need to build engaging user experiences with camera functionality, media playback, barcode scanning, and more.

## Features

- 🎯 **Kiosk-focused Components**: Pre-built page components for common kiosk workflows
- 📷 **Media Handling**: Camera, video player, and audio visualization components
- 🔍 **Scanning**: Barcode and QR code scanning capabilities
- 🎨 **Theming**: Comprehensive theming system with CSS variables
- 📱 **Responsive**: Mobile-first design with touch-friendly interfaces
- ⚡ **Vue 3**: Built with Vue 3 Composition API and TypeScript
- 🛠 **Composables**: Reusable logic for media, animations, and more

## Installation

```bash
npm install @gramercytech/gx-componentkit
```

## Quick Start

### Global Installation

```javascript
import { createApp } from 'vue'
import GxComponentKit from '@gramercytech/gx-componentkit'
import '@gramercytech/gx-componentkit/style.css'

const app = createApp(App)
app.use(GxComponentKit)
app.mount('#app')
```

### Individual Component Import

```javascript
import { GxPageStart, GxModal, GxCountdown } from '@gramercytech/gx-componentkit'
import '@gramercytech/gx-componentkit/style.css'
```

## Components

### Page Components

- **GxPageStart** - Landing page with logo, title, and start button
- **GxPageInstructions** - Instructions and user input collection
- **GxPagePrompt** - Prompt selection and user interaction
- **GxPageCamera** - Camera capture interface
- **GxPageCameraReview** - Review captured media
- **GxPageResults** - Display results and options
- **GxPageFinal** - Final confirmation and completion
- **GxPageLoading** - Loading states with spinner
- **GxPageShare** - Social sharing interface
- **GxPageForm** - Form input collection
- **GxPageQuiz** - Quiz and question interface
- **GxPageTerms** - Terms and conditions display

### UI Components

- **GxModal** - Customizable modal dialogs
- **GxCountdown** - Countdown timer with progress
- **GxVideoPlayer** - Video player with custom controls
- **GxCamera** - Camera capture component
- **GxAudioVisualizer** - Audio visualization
- **GxBarcodeScanner** - Barcode/QR code scanner
- **GxThemeWrapper** - Theme application wrapper

## Composables

### useMedia
Handles camera, video, and audio operations:

```javascript
import { useMedia } from '@gramercytech/gx-componentkit'

const {
  videoStream,
  audioStream,
  startRecording,
  stopRecording,
  photoBlob,
  setVideoDevice
} = useMedia()
```

### useAnimations
Provides animation utilities:

```javascript
import { useAnimations } from '@gramercytech/gx-componentkit'

const {
  fadeIn,
  fadeOut,
  slideIn,
  slideOut,
  addAnimation
} = useAnimations()
```

### useScanning
Manages barcode/QR code scanning:

```javascript
import { useScanning } from '@gramercytech/gx-componentkit'

const {
  isScanning,
  scanResult,
  startScanning,
  stopScanning
} = useScanning()
```

### useErrors
Error state management:

```javascript
import { useErrors } from '@gramercytech/gx-componentkit'

const {
  errorMessages,
  addError,
  clearErrors
} = useErrors()
```

### useCameraBorder
Camera border styling and animations:

```javascript
import { useCameraBorder } from '@gramercytech/gx-componentkit'

const {
  borderStyles,
  setBorderColor,
  animateBorder
} = useCameraBorder()
```

## Usage Examples

### Basic Kiosk Page

```vue
<template>
  <GxPageStart
    :plugin-vars="pluginVars"
    :asset-urls="assetUrls"
    :strings-list="stringsList"
    :theme="theme"
    @start="handleStart"
    @idle-timeout="handleTimeout"
  />
</template>

<script setup>
import { GxPageStart } from '@gramercytech/gx-componentkit'

const pluginVars = {
  primary_color: '#007bff',
  idle_timeout: '30'
}

const assetUrls = {
  main_logo: '/path/to/logo.png'
}

const stringsList = {
  start_line_one: 'Welcome!',
  start_line_two: 'Touch to begin'
}

const theme = {
  background_color: '#ffffff',
  text_color: '#333333'
}

const handleStart = () => {
  // Handle start action
}

const handleTimeout = () => {
  // Handle idle timeout
}
</script>
```

### Using Composables

```vue
<template>
  <div>
    <video ref="videoElement" autoplay muted></video>
    <button @click="startRecording({ video: videoElement })">
      Start Recording
    </button>
    <button @click="stopRecording">Stop Recording</button>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { useMedia } from '@gramercytech/gx-componentkit'

const videoElement = ref()
const {
  videoStream,
  startRecording,
  stopRecording,
  videoBlob
} = useMedia()

onMounted(async () => {
  // Set up video stream
  if (videoElement.value) {
    videoElement.value.srcObject = videoStream.value
  }
})
</script>
```

## Theming

The library supports comprehensive theming through CSS variables:

```css
:root {
  --gx-primary-color: #007bff;
  --gx-secondary-color: #6c757d;
  --gx-background-color: #ffffff;
  --gx-text-color: #333333;
  --gx-border-radius: 8px;
}
```

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import type {
  PluginVars,
  AssetList,
  StringsList,
  Theme,
  MediaDevice,
  RecordingOptions
} from '@gramercytech/gx-componentkit'
```

## Browser Support

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Build with watch mode
npm run build:watch
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

ISC License - see LICENSE file for details.

## Related Projects

- [gx-toolkit](https://github.com/GramercyTech/gx-toolkit) - Development tools for the platform
- [z-plugin-components](https://github.com/GramercyTech/z-plugin-components) - Legacy component library (being migrated to this library)

## Support

For support and questions, please open an issue on GitHub or contact the development team.