New Component: Rating (#8182)

* refactor: enhance Rating component with allowHalf feature and introduce RatingOption component

* feat: add rating demos and docs

* refactor: rename modelValue to value in useRating props and update related logic

* refactor: update Rating component to use 'value' prop & add ControlledDemo

Author: tanerengiiin

apps/showcase/demo/rating/allow-half-demo.tsx

@@ -0,0 +1,13 @@
+import { Rating } from 'primereact/rating';
+
+function AllowHalfDemo() {
+    return (
+        <div className="card flex justify-center">
+            <Rating value={3} allowHalf={false}>
+                <Rating.Option />
+            </Rating>
+        </div>
+    );
+}
+
+export default AllowHalfDemo;

apps/showcase/demo/rating/basic-demo.tsx

@@ -3,7 +3,9 @@ import { Rating } from 'primereact/rating';
 function BasicDemo() {
     return (
         <div className="card flex justify-center">
-            <Rating />
+            <Rating value={3.5}>
+                <Rating.Option />
+            </Rating>
         </div>
     );
 }

apps/showcase/demo/rating/controlled-demo.tsx

@@ -0,0 +1,29 @@
+import { useRatingChangeEvent } from '@primereact/types/shared/rating';
+import { Button } from 'primereact/button';
+import { Rating } from 'primereact/rating';
+import React from 'react';
+
+function ControlledDemo() {
+    const [value, setValue] = React.useState<number | undefined>(4);
+
+    return (
+        <div className="card flex flex-col justify-center gap-4">
+            <div className="flex items-center gap-2">
+                <Button onClick={() => setValue(2.5)} severity="secondary" variant="outlined">
+                    2.5 Star
+                </Button>
+                <Button onClick={() => setValue(3)} severity="secondary" variant="outlined">
+                    3 Star
+                </Button>
+                <Button onClick={() => setValue(3.5)} severity="secondary" variant="outlined">
+                    3.5 Star
+                </Button>
+            </div>
+            <Rating value={value} onValueChange={(e: useRatingChangeEvent) => setValue(e.value)}>
+                <Rating.Option />
+            </Rating>
+        </div>
+    );
+}
+
+export default ControlledDemo;

apps/showcase/demo/rating/disabled-demo.tsx

@@ -3,7 +3,9 @@ import { Rating } from 'primereact/rating';
 function DisabledDemo() {
     return (
         <div className="card flex justify-center">
-            <Rating modelValue={3} disabled />
+            <Rating value={3} disabled>
+                <Rating.Option />
+            </Rating>
         </div>
     );
 }

apps/showcase/demo/rating/readonly-demo.tsx

@@ -3,7 +3,9 @@ import { Rating } from 'primereact/rating';
 function ReadOnlyDemo() {
     return (
         <div className="card flex justify-center">
-            <Rating modelValue={3} readOnly />
+            <Rating value={3} readOnly>
+                <Rating.Option />
+            </Rating>
         </div>
     );
 }

apps/showcase/demo/rating/stars-demo.tsx

@@ -3,7 +3,9 @@ import { Rating } from 'primereact/rating';
 function StarsDemo() {
     return (
         <div className="card flex justify-center">
-            <Rating stars={10} />
+            <Rating stars={10}>
+                <Rating.Option />
+            </Rating>
         </div>
     );
 }

apps/showcase/demo/rating/template-demo.tsx

@@ -2,12 +2,24 @@ import { Rating } from 'primereact/rating';
 
 function TemplateDemo() {
     return (
-        <div className="card flex justify-center">
-            <Rating
-                modelValue={3}
-                onIcon={<img src="https://primefaces.org/cdn/primevue/images/rating/custom-onicon.png" height="24" width="24" />}
-                offIcon={<img src="https://primefaces.org/cdn/primevue/images/rating/custom-officon.png" height="24" width="24" />}
-            />
+        <div className="card flex flex-col gap-6 justify-center">
+            <Rating value={3}>
+                <Rating.Option onIcon={<span className="text-surface-950 dark:text-surface-0 text-2xl select-none">A</span>} offIcon={<span className="text-surface-300 dark:text-surface-700 text-2xl select-none">A</span>} />
+            </Rating>
+            <Rating value={3} allowHalf={false}>
+                <Rating.Option
+                    onIcon={
+                        <span className="w-6 h-6">
+                            <img src="https://primefaces.org/cdn/primevue/images/rating/custom-onicon.png" className="w-6 h-6" />
+                        </span>
+                    }
+                    offIcon={
+                        <span className="w-6 h-6">
+                            <img src="https://primefaces.org/cdn/primevue/images/rating/custom-officon.png" />
+                        </span>
+                    }
+                />
+            </Rating>
         </div>
     );
 }

apps/showcase/docs/components/rating/features.mdx

@@ -11,17 +11,31 @@ import { Rating } from 'primereact/rating';
 ```
 
 ```tsx
-<Rating />
+<Rating>
+    <Rating.Option value={1} />
+</Rating>
 ```
 
 ## Examples
 
 ### Basic
 
-Rating is used with the `modelValue` property.
+Rating is used with the `value` property.
 
 <DocDemoViewer name="rating:basic-demo" />
 
+### Half Stars
+
+Use `allowHalf` property to allow half stars.
+
+<DocDemoViewer name="rating:allow-half-demo" />
+
+### Controlled
+
+Use `onValueChange` to listen to value changes.
+
+<DocDemoViewer name="rating:controlled-demo" />
+
 ### Number of Stars
 
 Number of stars to display is defined with `stars` property.

packages/headless/src/rating/useRating.props.ts

@@ -1,10 +1,11 @@
 import type { useRatingProps } from '@primereact/types/shared/rating';
 
 export const defaultProps: useRatingProps = {
-    modelValue: undefined,
+    value: undefined,
     defaultValue: undefined,
     stars: 5,
     disabled: false,
     readOnly: false,
-    onChange: undefined
+    allowHalf: true,
+    onValueChange: undefined
 };

packages/headless/src/rating/useRating.ts

@@ -8,97 +8,120 @@ export const useRating = withHeadless({
     defaultProps,
     setup: ({ props, elementRef }) => {
         const { readOnly, disabled } = props;
-        const [valueState, setValueState] = React.useState(props.modelValue);
-        const focusedOptionIndexRef = React.useRef(-1);
-        const isFocusVisibleItemRef = React.useRef(false);
-        const [focusedOptionIndex, setFocusedOptionIndex] = React.useState(-1);
+        const [valueState, setValueState] = React.useState(props.allowHalf ? (props.defaultValue ?? props.value) : Math.ceil(props.defaultValue ?? props.value ?? 0));
+        const [hoverValueState, setHoverValueState] = React.useState<number | undefined>(undefined);
+        const [focusedOptionIndex, setFocusedOptionIndex] = React.useState<number | undefined>(undefined);
         const [isFocusVisibleItem, setIsFocusVisibleItem] = React.useState(false);
 
+        const hoverValueRef = React.useRef<number | undefined>(undefined);
+
         const state = {
             value: valueState,
+            hoverValue: hoverValueState,
             focusedOptionIndex,
             isFocusVisibleItem
         };
 
         // methods
-        const setFocusedOption = (val: number) => {
-            focusedOptionIndexRef.current = val;
-            setFocusedOptionIndex(val);
-        };
 
-        const setIsFocusVisible = (val: boolean) => {
-            isFocusVisibleItemRef.current = val;
-            setIsFocusVisibleItem(val);
-        };
+        const onInputFocus = (event: React.FocusEvent<HTMLInputElement>) => {
+            const inputValue = parseFloat(event.target.value);
+            const starIndex = Math.ceil(inputValue);
 
-        const onOptionClick = (event: React.MouseEvent<HTMLDivElement>, value: number) => {
-            if (!readOnly && !disabled) {
-                onOptionSelect(value);
-                setIsFocusVisible(false);
+            setFocusedOptionIndex(starIndex);
 
-                const firstFocusableEl = getFirstFocusableElement(event.currentTarget);
+            const native = event.nativeEvent as FocusEvent & {
+                sourceCapabilities?: {
+                    firesTouchEvents: boolean;
+                };
+            };
 
-                if (firstFocusableEl && firstFocusableEl instanceof HTMLElement) {
-                    focus(firstFocusableEl);
-                }
-            }
+            setIsFocusVisibleItem(native.sourceCapabilities?.firesTouchEvents === false);
         };
 
-        const onOptionSelect = (value: number) => {
-            if (readOnly || disabled) return;
+        const onInputBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+            const relatedTarget = event.relatedTarget as HTMLElement | null;
 
-            if (focusedOptionIndexRef.current === value || valueState === value) {
-                setFocusedOption(-1);
-                setIsFocusVisible(false);
-                setValueState(undefined);
-            } else {
-                setFocusedOption(value);
-                setIsFocusVisible(true);
-                setValueState(value);
+            if (relatedTarget && elementRef.current?.contains(relatedTarget)) {
+                return;
             }
+
+            setFocusedOptionIndex(undefined);
         };
 
-        const onFocus = (event: React.FocusEvent<HTMLInputElement>, value: number) => {
-            if (readOnly || disabled) return;
+        const onInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+            setValueState(Number(event.target.value));
+            const inputValue = parseFloat(event.target.value);
+            const starIndex = Math.ceil(inputValue);
 
-            setFocusedOption(value);
-            setIsFocusVisible((event.nativeEvent as FocusEvent & { sourceCapabilities?: { firesTouchEvents: boolean } | null }).sourceCapabilities?.firesTouchEvents === false);
+            setFocusedOptionIndex(starIndex);
+            setIsFocusVisibleItem(true);
         };
 
-        const onBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+        const onOptionClick = (event: React.MouseEvent<HTMLDivElement>, value: number | undefined) => {
             if (readOnly || disabled) return;
 
-            const relatedTarget = event.relatedTarget as HTMLElement | null;
+            const effectiveValue = props.allowHalf ? value : Math.ceil(value ?? 0);
 
-            if (relatedTarget && elementRef.current?.contains(relatedTarget)) {
-                return;
+            if (hoverValueRef.current === effectiveValue) {
+                setHoverValueState(undefined);
             }
 
-            setFocusedOption(-1);
-            setIsFocusVisible(false);
-            //            formField.onBlur?.();
+            setValueState((prev) => (prev === effectiveValue ? undefined : effectiveValue));
+            setIsFocusVisibleItem(false);
+
+            const firstFocusableEl = getFirstFocusableElement(event.currentTarget);
+
+            if (firstFocusableEl && firstFocusableEl instanceof HTMLElement) {
+                focus(firstFocusableEl);
+            }
         };
 
-        const onChange = (event: React.ChangeEvent<HTMLInputElement>, value: number) => {
+        const onOptionHover = (event: React.PointerEvent<HTMLDivElement>, value: number | undefined) => {
             if (readOnly || disabled) return;
 
-            onOptionSelect(value);
-            setIsFocusVisible(true);
+            setFocusedOptionIndex(undefined);
+            const newValue = value ? (props.allowHalf ? value : Math.ceil(value ?? 0)) : undefined;
+
+            setHoverValueState(newValue);
+            hoverValueRef.current = newValue;
+        };
+
+        const getOptionState = (value: number) => {
+            const effectiveValue = hoverValueState ?? valueState ?? 0;
+
+            const floor = Math.floor(effectiveValue);
+
+            let state = 'empty';
+
+            if (value <= floor) {
+                state = 'filled';
+            } else if (value === floor + 1 && !Number.isInteger(effectiveValue)) {
+                state = 'half';
+            }
+
+            return state;
         };
 
         // effects
 
         React.useEffect(() => {
-            props?.onChange?.({ value: valueState, originalEvent: null });
+            props?.onValueChange?.({ value: valueState, originalEvent: null });
         }, [valueState]);
 
+        React.useEffect(() => {
+            setValueState(props.allowHalf ? (props.defaultValue ?? props.value) : Math.ceil(props.defaultValue ?? props.value ?? 0));
+        }, [props.value, props.defaultValue, props.allowHalf]);
+
         return {
             state,
             // methods
+            onInputFocus,
+            onInputBlur,
+            onInputChange,
+            getOptionState,
             onOptionClick,
-            onFocus,
-            onBlur,
-            onChange
+            onOptionHover
         };
     }
 });