# Rating Stars Widget

## Overview

The Rating Stars widget is an interactive OWL component for Odoo 18 that provides a 5-star rating interface with full accessibility support.

## Features

- ⭐ **Interactive Star Selection**: Click any star to set the rating (1-5)
- 👆 **Hover Feedback**: Visual preview of rating on hover
- ⌨️ **Keyboard Navigation**: Full keyboard support with arrow keys, Enter, Home, and End
- ♿ **Accessibility**: ARIA labels and screen reader support
- 📱 **Touch-Friendly**: Optimized for mobile devices with larger touch targets
- 🎨 **Responsive Design**: Adapts to different screen sizes
- 🌓 **Theme Support**: Dark mode and high contrast mode support

## Usage

### In OWL Components

```javascript
import { RatingStars } from "@helpdesk_rating_five_stars/js/rating_stars";

// In your component template
<RatingStars 
    value="state.rating" 
    onChange.bind="onRatingChange"
    size="'medium'"
    readonly="false"
/>

// In your component class
onRatingChange(newValue) {
    this.state.rating = newValue;
    console.log(`Rating changed to: ${newValue}`);
}
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | Number | 0 | Current rating value (0-5) |
| `readonly` | Boolean | false | Whether the widget is read-only |
| `onChange` | Function | undefined | Callback function when rating changes |
| `size` | String | 'medium' | Size variant: 'small', 'medium', or 'large' |

### In QWeb Templates

```xml
<t t-component="RatingStars" 
   t-props="{
       value: rating,
       onChange: (val) => this.updateRating(val),
       size: 'large',
       readonly: false
   }"
/>
```

### Size Variants

- **Small** (`size="'small'"`): 16px stars, compact for list views
- **Medium** (`size="'medium'"`): 24px stars, default size
- **Large** (`size="'large'"`): 36px stars, prominent for forms

## Keyboard Navigation

| Key | Action |
|-----|--------|
| `Arrow Right` / `Arrow Up` | Increase rating by 1 star |
| `Arrow Left` / `Arrow Down` | Decrease rating by 1 star |
| `Home` | Jump to 1 star |
| `End` | Jump to 5 stars |
| `Enter` / `Space` | Confirm current selection |
| `Tab` | Move focus to/from widget |

## Accessibility

The widget includes comprehensive accessibility features:

- **ARIA Role**: `slider` role for the container
- **ARIA Labels**: Descriptive labels for each star (e.g., "Rate 3 stars out of 5")
- **ARIA Properties**: 
  - `aria-valuemin="1"`
  - `aria-valuemax="5"`
  - `aria-valuenow` (current value)
  - `aria-readonly` (when readonly)
- **Keyboard Support**: Full keyboard navigation
- **Focus Indicators**: Clear visual focus indicators
- **Screen Reader Support**: Announces rating changes

## Styling

The widget uses SCSS for styling with the following features:

- CSS transitions for smooth animations
- Hover effects with scale transform
- Focus indicators for keyboard navigation
- Responsive breakpoints for mobile
- Support for reduced motion preferences
- High contrast mode support
- Dark mode support

### Custom Styling

You can override the default styles by targeting these CSS classes:

```scss
.rating-stars-container {
    // Container styles
}

.rating-star {
    // Individual star styles
}

.rating-star-filled {
    // Filled star color
    color: #ffc107;
}

.rating-star-empty {
    // Empty star color
    color: #e0e0e0;
}

.rating-star-interactive {
    // Interactive star styles (hover, cursor)
}

.rating-star-focused {
    // Focused star styles (keyboard navigation)
}
```

## Browser Support

- Chrome/Edge: ✅ Full support
- Firefox: ✅ Full support
- Safari: ✅ Full support
- Mobile browsers: ✅ Full support with touch optimization

## Examples

### Read-only Display

```javascript
<RatingStars 
    value="4" 
    readonly="true"
    size="'small'"
/>
```

### Interactive Rating Form

```javascript
<RatingStars 
    value="state.customerRating" 
    onChange.bind="handleRatingChange"
    size="'large'"
/>
```

### With Validation

```javascript
onRatingChange(newValue) {
    if (newValue >= 1 && newValue <= 5) {
        this.state.rating = newValue;
        this.validateForm();
    }
}
```

## Testing

The widget can be tested using the demo HTML file:

```
customaddons/helpdesk_rating_five_stars/static/description/widget_demo.html
```

Open this file in a browser to see interactive examples of the widget in action.

## Requirements

- Odoo 18
- OWL (Odoo Web Library) - included in Odoo 18
- Modern browser with ES6 support

## License

LGPL-3