mirror of
https://github.com/pacnpal/thrillwiki_laravel.git
synced 2025-12-20 08:31:09 -05:00
136 lines
3.1 KiB
Markdown
136 lines
3.1 KiB
Markdown
# Search Components Documentation
|
|
|
|
## AutocompleteComponent
|
|
|
|
### Features
|
|
- Real-time suggestions with 300ms debounce
|
|
- Keyboard navigation (up/down/enter)
|
|
- Dark mode compatibility
|
|
- Mobile-responsive design
|
|
- Accessibility support (ARIA labels, roles)
|
|
|
|
### Keyboard Shortcuts
|
|
- `↑` - Navigate to previous suggestion
|
|
- `↓` - Navigate to next suggestion
|
|
- `Enter` - Select current suggestion
|
|
- `Esc` - Clear and close suggestions
|
|
|
|
### Usage Example
|
|
```php
|
|
<livewire:autocomplete-component
|
|
:endpoint="route('api.search.suggestions')"
|
|
:placeholder="'Search for rides, parks...'"
|
|
/>
|
|
```
|
|
|
|
### Integration with SearchComponent
|
|
The AutocompleteComponent works seamlessly with SearchComponent through:
|
|
1. Event communication for selected suggestions
|
|
2. Shared state management
|
|
3. Coordinated filter updates
|
|
|
|
## SearchComponent
|
|
|
|
### Features
|
|
- Real-time filtering
|
|
- Multiple filter combinations
|
|
- State persistence
|
|
- Dark mode support
|
|
- Mobile-responsive layout
|
|
|
|
### Filter Combinations
|
|
Valid filter combinations include:
|
|
- Type (park, ride, area)
|
|
- Location (country, region)
|
|
- Status (open, closed, planned)
|
|
- Category (specific to type)
|
|
|
|
### Mobile Responsiveness
|
|
- Collapsible filter panel
|
|
- Touch-friendly inputs
|
|
- Responsive grid layout
|
|
- Optimized for various screen sizes
|
|
|
|
### Dark Mode Implementation
|
|
- Consistent with system theme
|
|
- Maintains contrast ratios
|
|
- Preserves readability
|
|
- Smooth transitions
|
|
|
|
### Performance Considerations
|
|
- 300ms debounce on search input
|
|
- Optimized query execution
|
|
- Minimal re-renders
|
|
- Efficient state updates
|
|
|
|
## Accessibility Features
|
|
|
|
### ARIA Attributes
|
|
- `aria-expanded`: Indicates suggestion panel state
|
|
- `aria-activedescendant`: Identifies active suggestion
|
|
- `aria-controls`: Links input to suggestions
|
|
- `role="combobox"`: Identifies autocomplete input
|
|
- `role="listbox"`: Identifies suggestions list
|
|
|
|
### Keyboard Support
|
|
- Full keyboard navigation
|
|
- Focus management
|
|
- Skip links
|
|
- Clear focus indicators
|
|
|
|
### Screen Reader Support
|
|
- Meaningful labels
|
|
- Status announcements
|
|
- Clear instructions
|
|
- Error notifications
|
|
|
|
## API Integration
|
|
|
|
### Endpoints
|
|
1. `/api/search/suggestions`
|
|
- Returns autocomplete suggestions
|
|
- Parameters: query, type, limit
|
|
- Response: JSON array of matches
|
|
|
|
2. `/api/search`
|
|
- Performs full search
|
|
- Parameters: query, filters, page
|
|
- Response: Paginated results
|
|
|
|
### Response Format
|
|
```json
|
|
{
|
|
"data": [...],
|
|
"meta": {
|
|
"total": 100,
|
|
"per_page": 15,
|
|
"current_page": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
## Testing Guidelines
|
|
|
|
### Filter Testing
|
|
1. Test all possible filter combinations
|
|
2. Verify filter state persistence
|
|
3. Check filter reset functionality
|
|
4. Validate filter validation rules
|
|
|
|
### Keyboard Navigation Testing
|
|
1. Test arrow key navigation
|
|
2. Verify enter key selection
|
|
3. Check escape key behavior
|
|
4. Validate focus management
|
|
|
|
### Mobile Testing
|
|
1. Test on various screen sizes
|
|
2. Verify touch interactions
|
|
3. Check responsive layouts
|
|
4. Validate filter panel behavior
|
|
|
|
### Dark Mode Testing
|
|
1. Test theme switching
|
|
2. Verify color contrast
|
|
3. Check transition effects
|
|
4. Validate component states |