# Mobile App Interactive Components Guide

**Last Updated:** 2026-02-02

## Overview

This guide documents the interactive components created for the mobile app feature page (`product_mobile_app.php`). These components replace static screenshots with engaging, interactive elements that showcase the mobile app's functionality.

## Component Architecture

### File Structure

```
v2/components/mobile-app/
├── calendar-component.php          # Calendar with date selection
├── timer-component.php             # Time tracking timer
├── absence-form-component.php      # Absence request form
├── task-list-component.php         # Checklist/task list
└── dashboard-cards-component.php   # Dashboard cards

v2/css/
└── mobile-app-components.css      # Component styles and animations
```

### Technology Stack

- **Alpine.js**: Component state management and interactivity
- **CSS3**: Animations, transitions, and styling
- **PHP**: Component includes and server-side rendering
- **AOS**: Scroll-triggered animations (already available)

## Component Specifications

### 1. Calendar Component

**File:** `v2/components/mobile-app/calendar-component.php`

**Purpose:** Interactive calendar showing shift planning with date selection and availability timeline.

**Features:**
- Monthly calendar grid (January 2026)
- Highlighted dates with shifts (blue circles)
- Selected date indicator (darker blue)
- Availability timeline with time slots
- "Verfügbar" toggle button
- Click interaction for date selection
- Keyboard navigation support

**Alpine.js Data:**
- `selectedDate`: Currently selected date
- `isAvailable`: Availability status
- `currentMonth`: Display month
- `currentWeek`: Display week
- `calendarDays`: Array of calendar day objects
- `timeSlots`: Array of time slot objects

**Usage:**
```php
<?php include '../components/mobile-app/calendar-component.php'; ?>
```

**Accessibility:**
- ARIA labels for dates
- Keyboard navigation (Enter/Space)
- Focus indicators
- Screen reader support

### 2. Timer Component

**File:** `v2/components/mobile-app/timer-component.php`

**Purpose:** Time tracking timer with circular progress indicator.

**Features:**
- Large time display (00:00 format)
- Circular progress indicator (SVG)
- Location indicator
- Status badge
- Swipe hint
- Optional scroll-based time increment

**Alpine.js Data:**
- `seconds`: Current time in seconds
- `isRunning`: Timer running state
- `status`: Timer status text
- `maxSeconds`: Maximum time (8 hours)

**Methods:**
- `formattedTime()`: Format seconds as MM:SS or HH:MM:SS
- `progressOffset()`: Calculate progress circle offset
- `startTimer()`: Start timer countdown

**Usage:**
```php
<?php include '../components/mobile-app/timer-component.php'; ?>
```

### 3. Absence Form Component

**File:** `v2/components/mobile-app/absence-form-component.php`

**Purpose:** Absence request form with date pickers, toggles, and dropdown.

**Features:**
- Start/End date fields (readonly, styled)
- Toggle switches (Half first/last day)
- Dropdown selector (Absence type)
- Note textarea
- Submit button with loading state
- Form validation feedback (visual)

**Alpine.js Data:**
- `halfFirstDay`: Toggle state
- `halfLastDay`: Toggle state
- `absenceType`: Selected absence type
- `note`: Note text
- `isSubmitting`: Submission state
- `submitText`: Button text

**Methods:**
- `submitForm()`: Handle form submission (visual feedback only)

**Usage:**
```php
<?php include '../components/mobile-app/absence-form-component.php'; ?>
```

**Accessibility:**
- Form labels
- Keyboard navigation
- Focus management
- ARIA states

### 4. Task List Component

**File:** `v2/components/mobile-app/task-list-component.php`

**Purpose:** Checklist/task list with completion status.

**Features:**
- Task items with icons
- Completion status (0/4 format)
- Warning message banner
- "End shift" button
- Click interaction to toggle completion
- Visual status indicators

**Alpine.js Data:**
- `tasks`: Array of task objects

**Task Object Structure:**
```javascript
{
    name: 'Task name',
    date: 'Date string',
    completed: 0,
    total: 4,
    icon: 'Emoji or SVG',
    iconBg: 'Background color'
}
```

**Methods:**
- `toggleTask(index)`: Toggle task completion
- `endShift()`: Handle shift end action

**Usage:**
```php
<?php include '../components/mobile-app/task-list-component.php'; ?>
```

### 5. Dashboard Cards Component

**File:** `v2/components/mobile-app/dashboard-cards-component.php`

**Purpose:** Dashboard cards showing various app features.

**Features:**
- Greeting card
- Timer card (START with time)
- Mini calendar view
- Open shifts card
- Salary visualization (dot grid)
- Weather widget
- Staggered fade-in animations

**Alpine.js Data:**
- `seconds`: Timer seconds
- `timerStatus`: Timer status text
- `calendarDays`: Array of calendar day objects
- `salaryDots`: Array of boolean values for salary visualization

**Methods:**
- `formattedTime()`: Format timer display

**Usage:**
```php
<?php include '../components/mobile-app/dashboard-cards-component.php'; ?>
```

## CSS Styling

### CSS File: `v2/css/mobile-app-components.css`

**Key Features:**
- CSS custom properties (variables) for theming
- Mobile device frame styling
- Component-specific styles
- Animation keyframes
- Responsive breakpoints
- Accessibility styles
- Print styles
- Reduced motion support

### CSS Variables

```css
--mobile-app-bg: #ffffff
--mobile-app-text: #333333
--mobile-app-blue: #4D8EF3
--mobile-app-blue-dark: #286bcd
--mobile-app-gray: #EDEFF3
--mobile-app-gray-light: #fbfbfb
--mobile-app-border-radius: 16px
--mobile-app-shadow: Box shadow values
--mobile-app-shadow-lg: Large box shadow values
```

### Animations

- `fadeIn`: Fade in with translateY
- `slideIn`: Slide in from left
- `pulse`: Pulsing opacity
- `scaleIn`: Scale in animation
- `shimmer`: Shimmer effect (for future use)
- `rotate`: Rotation animation

### Performance Optimizations

- GPU-accelerated transforms (`transform: translateZ(0)`)
- `will-change` property for animated elements
- Smooth transitions (0.2s-0.3s ease)
- Reduced motion media query support

## Integration

### In `product_mobile_app.php`

**CSS Include:**
```php
<link rel="stylesheet" href="/v2/css/mobile-app-components.css?v=<?php echo filemtime(__DIR__ . '/../css/mobile-app-components.css'); ?>">
```

**Component Includes:**
- Hero section: Dashboard cards component
- Schichtplanung section: Calendar component
- Zeiterfassung section: Timer component
- Abwesenheiten section: Absence form component

### Lazy Loading

Components below the fold use Alpine.js `x-intersect` directive for lazy loading:

```html
<div x-data="{ loaded: false }" x-intersect="loaded = true">
    <div x-show="loaded" x-transition>
        <template x-if="loaded">
            <?php include '../components/mobile-app/component.php'; ?>
        </template>
    </div>
</div>
```

## Accessibility

### ARIA Labels

All interactive components include:
- `role` attributes
- `aria-label` for buttons and interactive elements
- `aria-pressed` for toggle states
- `aria-busy` for loading states
- `aria-pressed` for selected states

### Keyboard Navigation

- Tab navigation through interactive elements
- Enter/Space for activation
- Escape for closing modals/forms
- Focus indicators (2px outline with offset)

### Screen Reader Support

- Semantic HTML structure
- Descriptive labels
- State announcements
- Context information

## Responsive Design

### Breakpoints

- **Mobile**: Default styles (< 768px)
- **Tablet/Desktop**: Enhanced styles (≥ 768px)

### Mobile Optimizations

- Smaller font sizes
- Reduced padding
- Single column layouts
- Touch-friendly targets (min 44x44px)

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Android)

### Graceful Degradation

- Components work without JavaScript (static display)
- CSS animations degrade gracefully
- Reduced motion support for accessibility

## Performance Considerations

### Optimization Techniques

1. **GPU Acceleration**: Using `transform: translateZ(0)` for animations
2. **Lazy Loading**: Components below fold load on scroll
3. **Minimal JavaScript**: Alpine.js for lightweight interactivity
4. **CSS Transitions**: Hardware-accelerated CSS animations
5. **Reduced Motion**: Respects user preferences

### Loading Strategy

- Above fold: Load immediately
- Below fold: Lazy load on intersection
- CSS: Loaded with page
- JavaScript: Alpine.js already loaded globally

## Customization

### Theming

Update CSS variables in `mobile-app-components.css`:

```css
:root {
    --mobile-app-blue: #4D8EF3; /* Change primary color */
    --mobile-app-border-radius: 16px; /* Change border radius */
    /* etc. */
}
```

### Component Modification

1. Edit component PHP file
2. Update Alpine.js data/methods as needed
3. Adjust CSS classes/styles
4. Test across browsers

## Testing Checklist

- [ ] Visual comparison with screenshots
- [ ] Interactive functionality (clicks, hovers)
- [ ] Keyboard navigation
- [ ] Screen reader compatibility
- [ ] Responsive behavior (mobile/tablet/desktop)
- [ ] Cross-browser compatibility
- [ ] Performance (60fps animations)
- [ ] Accessibility (WCAG 2.1 AA)

## Future Enhancements

Potential improvements:
1. Add more interactive features (drag & drop, swipe gestures)
2. Create additional components (notifications, profile)
3. Add animation presets
4. Create component library documentation
5. Add Storybook or similar for component development

## Related Documentation

- [mobile-app-asset-requirements.md](mobile-app-asset-requirements.md) - Asset requirements
- [mobile-app-documentation.md](mobile-app-documentation.md) - Page documentation
- [mobile-app-content-strategy.md](mobile-app-content-strategy.md) - Content strategy