Components Overview

The UI Kit provides three categories of functionality:

UI Primitives

Low-level, accessible components from shadcn-vue. These are unstyled by default and themed via CSS variables.

Available Components

Component	Description
Accordion	Collapsible sections
Alert	Alert messages
AlertDialog	Confirmation dialog
AspectRatio	Aspect ratio container
Avatar	User avatar
Badge	Status badge
Button	Clickable button with variants and sizes
Calendar	Date picker
Card	Content container
Checkbox	Checkbox input
Collapsible	Collapsible content
Command	Command palette
ContextMenu	Right-click menu
Dialog	Modal dialog with overlay
DropdownMenu	Context menu
Form	Form wrapper with validation
HoverCard	Hover preview
Input	Text input with v-model support
Label	Form label
Menubar	Top menubar
NavigationMenu	Site navigation
Pagination	Page navigation
Popover	Floating content
Progress	Progress indicator
RadioGroup	Radio button group
ScrollArea	Custom scrollbar
Select	Dropdown select input
Separator	Visual divider
Sheet	Side panel
Skeleton	Loading placeholder
Slider	Range slider
Switch	Toggle switch
Table	Data table
Tabs	Tabbed navigation
Textarea	Multiline text input
Toaster (Sonner)	Toast notifications
Tooltip	Hover tooltip

Domain Components

Platform-specific components designed for GXP platform use cases.

Available Components

Component	Description
ActivityNotifications	Toast notification system for activity events
AudioVisualizer	Frequency bars and waveform timeline via Web Audio API
AwardIcon	SVG award/medal icon
BarcodeScanner	QR/barcode scanning using Quagga2 with dynamic import
Countdown	Idle timeout countdown with user interaction detection
FileUploader	File upload with image processing and multi-file support
Header	Page header with background image, logo, and video support
Leaderboard	Ranked list with placeholders, top-3 styling, and animations
Spinner	Loading spinner with sm/md/lg sizes
VideoPlayer	HTML5 video player with TypeScript props and events

Composables

Reusable composition functions for common platform functionality.

Available Composables

Composable	Description
useAnimations	Page transition animations with animate.css
useErrors	Shared error message state management
useMedia	Video/audio recording, device management, canvas processing
useNfcListener	NFC scan event handler via window.postMessage
useScanning	Barcode/QR scan state management

Component Architecture

File Structure

Each component follows this structure:

src/components/ui/<component-name>/
├── ComponentName.vue      # Main component
├── index.ts               # Exports
├── ComponentName.test.ts  # Unit tests
└── ComponentName.stories.ts  # Storybook stories

For domain components:

src/components/domain/<component-name>/
├── ComponentName.vue      # Main component
├── index.ts               # Exports
├── ComponentName.test.ts  # Unit tests
└── ComponentName.stories.ts  # Storybook stories

Naming Conventions

• PascalCase for component names: Button.vue, VideoPlayer.vue
• kebab-case for directories: video-player/, barcode-scanner/
• Type exports suffixed with type: ButtonVariants, InputProps

Props Pattern

Components use TypeScript interfaces for props:

interface Props {
  variant?: 'default' | 'secondary' | 'destructive'
  size?: 'default' | 'sm' | 'lg'
  disabled?: boolean
  class?: string
}

Event Pattern

Components emit typed events:

const emit = defineEmits<{
  (e: 'click', event: MouseEvent): void
  (e: 'update:modelValue', value: string): void
}>()

Using Components

Basic Import

import { Button, Input, VideoPlayer } from '@gxp-dev/uikit'

With Types

import { Button, type ButtonVariants } from '@gxp-dev/uikit'

Using Composables

import { useMedia, useScanning } from '@gxp-dev/uikit'

const { startRecording, stopRecording } = useMedia()
const { startScanning, stopScanning } = useScanning()

Accessing Variant Functions

Some components export variant functions for advanced styling:

import { buttonVariants } from '@gxp-dev/uikit'

// Use in custom component
const classes = buttonVariants({ variant: 'secondary', size: 'lg' })

Customizing Components

Via Props

<Button variant="secondary" size="lg" class="custom-class">
  Custom Button
</Button>

Via CSS Variables

Override the theme CSS variables:

:root {
  --primary: #your-color;
  --primary-foreground: #your-text-color;
}

Via Tailwind

Add custom classes that merge with defaults:

<Button class="rounded-full shadow-lg">
  Rounded Shadow Button
</Button>

Accessibility

All UI primitives from shadcn-vue are built on Reka UI, which provides:

• Keyboard navigation - Full keyboard support
• Focus management - Proper focus handling
• ARIA attributes - Semantic accessibility
• Screen reader support - Announced correctly

Storybook

Explore components interactively:

pnpm storybook

Each component has stories demonstrating:

• All variants and sizes
• Interactive controls
• Edge cases
• Accessibility features