helpdesk_rating_five_stars/static/src/README.md

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

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

<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:

.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

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

Interactive Rating Form

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

With Validation

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