# Ratti - React Star Rating Component

Ratti is a lightweight, customizable star rating component for React with TypeScript support. Features multiple variants, precision control, and smooth animations for modern web applications.

- [Ratti docs](https://github.com/yuskraft/ratti)
- [Guide: How to use this file in LLMs and code editors](https://github.com/yuskraft/ratti#readme)
- [Ratti release notes](https://github.com/yuskraft/ratti/releases)

## Ratti install notes

1. Ratti requires React 18+ and TypeScript support
2. Install using `npm install ratti` or `yarn add ratti`
3. Import the component: `import { RateStar } from 'ratti'`
4. Include the CSS: `import 'ratti/dist/ratti.css'`

## Ratti usage rules

1. We can give styles to the star rating component by adding CSS custom properties to the `.star-rating` element
2. The component can be customized using CSS custom properties if the customization is not possible using the existing props
3. If customization using CSS custom properties didn't work because of CSS specificity issues, you can use `!important` to override the existing styles
4. If a specific variant or feature doesn't exist in Ratti, you can create your own using the provided props and CSS custom properties
5. When using Ratti in responsive layouts, it should be responsive using CSS media queries
6. Only allowed props are existing Ratti prop names or standard React props
7. Ideally, you won't need to write any custom CSS. Using Ratti props and CSS custom properties is preferred
8. suggested - when designing, don't add a custom font unless it's necessary
9. suggested - use semantic color names for better theme support
10. don't add unnecessary wrapper divs unless it's necessary

## Ratti component props

### RateStar component

The main star rating component with the following props:

#### Required props
- None (all props are optional with sensible defaults)

#### Optional props
- `maxRating?: number` - Maximum number of stars (default: 5)
- `defaultValue?: number` - Default rating value (default: 0)
- `value?: number` - Controlled rating value
- `onChange?: (rating: number) => void` - Callback when rating changes
- `onHoverChange?: (hoverRating: number) => void` - Callback when hover rating changes
- `onBlur?: (event: React.FocusEvent<HTMLDivElement>) => void` - Callback on blur
- `disabled?: boolean` - Disable the component (default: false)
- `readOnly?: boolean` - Make the component read-only (default: false)
- `precision?: number` - Rating precision (default: 1)
- `activeColorsEnabled?: boolean` - Enable active color gradients (default: false)
- `customActiveColors?: string[]` - Custom colors for active states
- `variant?: StarRatingVariant` - Star variant (default: "default")
- `svgPathD?: string` - Custom SVG path for stars
- `className?: string` - Additional CSS classes
- `size?: number | string` - Star size in pixels or CSS value

#### Variant types
- `"default"` - Standard star rating with filled/empty states
- `"circle"` - Circular background with star icon
- `"square"` - Square background with star icon

## Ratti TypeScript types

### Main component types
- `StarRatingVariant` - Union type for star rating variants
  ```typescript
  type StarRatingVariant = "default" | "circle" | "square"
  ```

- `StarRatingProps` - Interface for the main component props
  ```typescript
  interface StarRatingProps {
    maxRating?: number;
    defaultValue?: number;
    value?: number;
    onChange?: (rating: number) => void;
    onHoverChange?: (hoverRating: number) => void;
    onBlur?: (event: React.FocusEvent<HTMLDivElement>) => void;
    disabled?: boolean;
    readOnly?: boolean;
    precision?: number;
    activeColorsEnabled?: boolean;
    customActiveColors?: string[];
    variant?: StarRatingVariant;
    svgPathD?: string;
    className?: string;
    size?: number | string;
  }
  ```

### Utility function types
- `roundToPrecision(value: number, precision: number): number` - Rounds a number to the specified precision
- `getColorForRating(value: number, maxRating: number, activeColorsEnabled: boolean, customActiveColors?: string[]): string | undefined` - Returns color based on rating value

### Star icon component types
- `StarIcon` props interface:
  ```typescript
  {
    fillPercentage?: number;
    starId: string;
    fillColor?: string;
    forcedColor?: string;
    svgPathD?: string;
    size?: number | string;
  }
  ```

### Constants
- `DEFAULT_RATING_COLORS: string[]` - Default color array for rating gradients
  ```typescript
  const DEFAULT_RATING_COLORS = [
    "#d32f2f", // Red
    "#ed6c02", // Orange
    "#ff9800", // Amber
    "#4caf50", // Green
    "#00a63d", // Dark Green
  ]
  ```

- `DEFAULT_SVG_PATH_D: string` - Default SVG path for star icon

### React event types
- `React.MouseEvent<HTMLDivElement>` - Mouse event for click and hover interactions
- `React.FocusEvent<HTMLDivElement>` - Focus event for blur handling
- `React.KeyboardEvent<HTMLDivElement>` - Keyboard event for navigation
- `ForwardedRef<HTMLDivElement>` - Forwarded ref type for component reference

## Ratti CSS custom properties

### Star rating container (.star-rating)
- `--star-size: 24px` - Size of each star
- `--star-gap: 4px` - Gap between stars
- `--star-color: #f59e0b` - Default star color
- `--star-hover-color: #fbbf24` - Star color on hover
- `--star-selected-color: #f59e0b` - Selected star color
- `--star-disabled-color: #94a3b8` - Disabled star color
- `--star-icon-on-bg: #ffffff` - Icon color on background variants
- `--star-bg-default: #dddddd` - Default background color
- `--star-bg-selected: var(--star-selected-color)` - Selected background color
- `--star-active-bg-color: var(--star-selected-color)` - Active background color
- `--star-transition: all 0.2s ease` - Transition timing
- `--star-hover-scale: 1.1` - Scale factor on hover
- `--star-active-scale: 0.95` - Scale factor on active
- `--star-outline: 2px solid var(--star-hover-color)` - Focus outline
- `--star-outline-offset: 3px` - Focus outline offset
- `--star-radius: 4px` - Border radius
- `--star-disabled-opacity: 0.6` - Disabled opacity
- `--star-fill-transition-duration: 0.1s` - Fill transition duration
- `--star-bg-padding: 8px` - Background padding for circle/square variants
- `--star-circle-radius: 50%` - Circle border radius
- `--star-square-radius: 4px` - Square border radius

### Star item (.star-item)
- Inherits all container properties
- `width: var(--star-size)` - Star width
- `height: var(--star-size)` - Star height
- `color: var(--star-color)` - Star color

### Star background (.star-background)
- `width: calc(var(--star-size) + var(--star-bg-padding, 8px))` - Background width
- `height: calc(var(--star-size) + var(--star-bg-padding, 8px))` - Background height
- `--active-bg: var(--star-active-bg-color, var(--star-bg-selected))` - Active background
- `--inactive-bg: var(--star-bg-default)` - Inactive background
- `--fill-stop: calc(var(--star-fill-percentage, 0) * 100%)` - Fill percentage

## Ratti examples

### Basic usage
```jsx
import { RateStar } from 'ratti';
import 'ratti/dist/ratti.css';

function App() {
  return <RateStar />;
}
```

### With custom props
```jsx
<RateStar 
  value={4.5}
  maxRating={5}
  precision={0.5}
  size={32}
  variant="circle"
  activeColorsEnabled={true}
  onChange={(rating) => console.log(rating)}
/>
```

### With custom styling
```jsx
<RateStar 
  className="my-custom-rating"
  style={{
    '--star-color': '#ff6b6b',
    '--star-size': '40px',
    '--star-gap': '8px'
  }}
/>
```

## Ratti accessibility

The component includes full accessibility support:
- ARIA attributes for screen readers
- Keyboard navigation (arrow keys, home, end, enter, space)
- Focus management
- High contrast support
- Semantic HTML structure

## Ratti themes

Ratti supports theming through CSS custom properties:
- Light/dark theme support
- Custom color schemes
- Responsive design
- High contrast mode

## Ratti best practices

1. Use semantic color names for better theme support
2. Provide meaningful aria-labels for screen readers
3. Test keyboard navigation thoroughly
4. Use appropriate precision values for your use case
5. Consider mobile touch interactions
6. Implement proper error handling for onChange callbacks
7. Use controlled components when you need to manage state externally
8. Test with different screen readers and assistive technologies