@progress/kendo-react-inputs 5.6.0-dev.202208251227 → 5.7.0-sig.202208281415

package/src/rating/Rating.tsx

@@ -0,0 +1,633 @@
+import * as React from 'react';
+import * as PropTypes from 'prop-types';
+import {
+    FormComponentProps,
+    classNames,
+    useDir,
+    Keys,
+    getTabIndex,
+    createPropsContext,
+    usePropsContext
+} from '@progress/kendo-react-common';
+
+import { RatingItem, RatingItemProps } from './RatingItem';
+import { ratingReducer, RATING_ACTION, RatingActionDispatch } from './rating-reducer';
+import { isSelected, isHalf, calcIsFirstHalf, isCorrectValue, toRound, getRemainder } from './utils';
+import {
+    RatingKeyboardEvent,
+    RatingItemMouseEvent,
+    RatingItemFocusEvent
+} from './models';
+
+import { messages, ratingAriaLabel } from '../messages';
+import { useLocalization } from '@progress/kendo-react-intl';
+
+/**
+ * Represents the properties of [Rating](% slug api_inputs_rating %) component.
+ */
+export interface RatingProps extends FormComponentProps {
+    /**
+     * Sets the `id` property of the top div element of the Rating.
+     */
+    id?: string;
+    /**
+     * Sets additional classes to the Rating.
+     */
+    className?: string;
+    /**
+     * Sets the `tabIndex` attribute.
+     */
+    tabIndex?: number;
+    /**
+     * Sets additional CSS styles to the Rating.
+     */
+    style?: React.CSSProperties;
+    /**
+     * Determines the children nodes.
+     */
+    children?: React.ReactNode;
+    /**
+     * Represents the rendered Rating item.
+     */
+    item?: React.ComponentType<RatingItemProps>;
+    /**
+     * Sets the current value of the Rating, used in controlled mode. [See example]({% slug item_customization_ratingitem %})
+     */
+    value?: number;
+    /**
+     * Sets the default value of the Rating, used in uncontrolled mode. [See example]({% slug controlled_rating %})
+     */
+    defaultValue?: number;
+    /**
+     * Sets the min possible icon value or star value in the main use-case.
+     */
+    min?: number;
+    /**
+     * Sets the max possible icon value or star value in the main use-case.
+     */
+    max?: number;
+    /**
+     * Sets the step value between the min and max value.
+     */
+    step?: number;
+    /**
+     * Determines the Rating direction `ltr` - by default, or `rtl`.
+     */
+    dir?: string;
+    /**
+     * Determines if the Rating has a label and is it a custom one.
+     */
+    label?: string;
+    /**
+     * Sets the `readonly` mode of the Rating, if it is set to `true`. [See example]({% slug label_rating %})
+     */
+    readonly?: boolean;
+    /**
+     * Sets the `disabled` mode of the Rating, if it is set to `true`. [See example]({% slug readonly_rating %})
+     */
+    disabled?: boolean;
+    /**
+     * Sets custom Rating icon, by default - star. [See example]({% slug disabled_rating %})
+     */
+    icon?: string;
+    /**
+     * Determines the selection mode. By default set to `continues`. [See example]({% slug icon_rating %})
+     */
+    selection?: 'continues' | 'single';
+    /**
+     * Determines the precision of the Rating. By default set to `item`. [See example]({% slug selection_rating %})
+     */
+    precision?: 'half' | 'item';
+    /**
+     * Determines if value represents half icon -> true, or not -> false. [See example]({% slug precision_rating %})
+     */
+    half?: boolean;
+    /**
+     * Triggered after value change. Gets outside access to the target element, the new value and the event type.
+     */
+    onChange?: (event: RatingChangeEvent) => void;
+    /**
+     * Triggered after `onClick` event. Gets outside access to the target element, the new value and the event type.
+     */
+    onClick?: (event: RatingItemMouseEvent) => void;
+    /**
+     * Triggered after `onKeyDown` event. Gets outside access to the target element, the new value and the event type.
+     */
+    onKeyDown?: (event: RatingKeyboardEvent) => void;
+    /**
+     * Triggered after `onFocus` event. Gets outside access to the target element and the event type.
+     */
+    onFocus?: (event: RatingItemFocusEvent) => void;
+    /**
+     * Triggered after `onBlur` event. Gets outside access to the target element and the event type.
+     */
+    onBlur?: (event: RatingItemFocusEvent) => void;
+    /* eslint-disable max-len */
+    /**
+     * Identifies the element(s) which will describe the component, similar to [HTML aria-describedby attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute).
+     * For example these elements could contain error or hint message.
+     */
+    ariaDescribedBy?: string;
+    // tslint:enable:max-line-length
+    /**
+     * Identifies the element(s) which will label the component.
+     */
+    ariaLabelledBy?: string;
+}
+
+/**
+ * Represents the target(element and props) of the RatingChangeEvent.
+ */
+export interface RatingHandle {
+    /**
+     * The current element or `null` if there is no one.
+     */
+    element: HTMLDivElement | null;
+    /**
+     * The props value of the Rating.
+     */
+    props: RatingProps;
+}
+
+/**
+ * Represents the return type of RatingChangeEvent.
+ */
+export interface RatingChangeEvent {
+    /**
+     * The current Rating value.
+     */
+    value: number;
+    /**
+     * The target of the RatingChangeEvent from RatingHandle.
+     */
+    target: RatingHandle;
+    /**
+     * The event of the RatingChangeEvent.
+     */
+    syntheticEvent: React.SyntheticEvent<any>;
+}
+
+/**
+ * @hidden
+ */
+const useRating = <T extends any>(
+    defaultValue: T | null,
+    args: any,
+    callback?: (newState: T, event: React.SyntheticEvent<any>) => void
+): [T | null, (action: RatingActionDispatch) => void] => {
+    const [state, setState] = React.useState<T | null>(defaultValue);
+    const handleDispatchAction = (action: RatingActionDispatch) => {
+        const newState = ratingReducer(args.state || state, { ...action, ...args });
+
+        if (callback) {
+            callback(newState, action.event as React.SyntheticEvent<any>);
+        }
+        setState(newState);
+    };
+
+    return [state, handleDispatchAction];
+};
+
+/**
+ * Represents the PropsContext of the `Rating` component.
+ * Used for global configuration of all `Rating` instances.
+ *
+ * For more information, refer to the [Inputs Props Context]({% slug props-context_inputs %}) article.
+ */
+export const RatingPropsContext = createPropsContext<RatingProps>();
+
+
+/**
+ * Represents the [KendoReact Rating component]({% slug overview_rating %}).
+ *
+ * Accepts properties of type [RatingProps]({% slug api_inputs_ratingprops %}).
+ * Obtaining the `ref` returns an object of type [RatingHandle]({% slug api_inputs_ratinghandle %}).
+ */
+export const Rating = React.forwardRef<RatingHandle | null, RatingProps>((directProps, ref) => {
+    const props = usePropsContext<RatingProps>(RatingPropsContext, directProps);
+
+    const localization = useLocalization();
+
+    const target = React.useRef<RatingHandle | null>(null);
+    const ratingRef = React.useRef<HTMLDivElement>(null);
+    const dir = useDir(ratingRef, props.dir);
+
+    React.useImperativeHandle(target, () => ({
+        element: ratingRef.current,
+        props
+    }));
+    React.useImperativeHandle<RatingHandle | null, RatingHandle | null>(ref, () => target.current);
+
+    const handleChange = React.useCallback(
+        (newValue: any, event: React.SyntheticEvent<any>) => {
+            if (props.onChange && target.current) {
+                props.onChange.call(undefined, {
+                    value: newValue,
+                    target: target.current,
+                    syntheticEvent: event
+                } as RatingChangeEvent);
+            }
+        },
+        [props.onChange]
+    );
+
+    const min = React.useMemo(
+        () => props.min !== undefined ? props.min : defaultProps.min,
+        [props.min]
+    );
+
+    const max = React.useMemo(
+        () => props.max !== undefined ? props.max : defaultProps.max,
+        [props.max]
+    );
+
+    const precision = React.useMemo(
+        () => props.precision || defaultProps.precision,
+        [props.precision]
+    );
+
+    const step = React.useMemo(
+        () => props.step !== undefined ? props.step : defaultProps.step,
+        [props.step]
+    );
+
+    const readonly = React.useMemo(
+        () => props.readonly || defaultProps.readonly,
+        [props.readonly]
+    );
+
+    const disabled = React.useMemo(
+        () => props.disabled || defaultProps.disabled,
+        [props.disabled]
+    );
+
+    const Item = React.useMemo(
+        () => props.item || defaultProps.item,
+        [props.item]
+    );
+
+    const [stateValue, dispatchStateValue] = useRating(
+        props.defaultValue || defaultProps.defaultValue,
+        {
+            state: props.value,
+            min,
+            max,
+            step: precision === 'half' ? step / 2 : step
+        },
+        handleChange
+    );
+
+    const [stateHover, dispatchStateHover] = useRating(
+        null,
+        {
+            state: props.value,
+            min,
+            max,
+            step: precision === 'half' ? step / 2 : step,
+            precision
+        }
+    );
+
+    const value: number | null = React.useMemo(
+        () => props.value || stateValue,
+        [props.value, stateValue]
+    );
+
+    const hoveredValue: number | null = React.useMemo(
+        () => stateHover,
+        [stateHover]
+    );
+
+    const selection: 'single' | 'continues' = React.useMemo(
+        () => props.selection || defaultProps.selection,
+        [props.selection]
+    );
+
+    const base: number = React.useMemo(
+        () => step / (precision === 'half' ? 2 : 1),
+        [step, precision]
+    );
+
+    const handleItemClick = React.useCallback(
+        (event: RatingItemMouseEvent) => {
+            if (!event.target || !event.target.element || readonly || disabled) {
+                return;
+            }
+
+            if (precision === 'half') {
+                const rect = event.target.element.getBoundingClientRect();
+                const isFirstHalf = calcIsFirstHalf(dir ? dir : 'ltr', rect, event.syntheticEvent.clientX);
+                const payload = isFirstHalf ? toRound(event.target.value - (step / 2), base) : event.target.value;
+                dispatchStateValue({ type: RATING_ACTION.select, payload, event: event.syntheticEvent });
+            } else {
+                dispatchStateValue({ type: RATING_ACTION.select, payload: event.target.value, event: event.syntheticEvent });
+            }
+
+            if (props.onClick) {
+                const ev: RatingItemMouseEvent = {
+                    value,
+                    target: target.current as any,
+                    syntheticEvent: event.syntheticEvent
+                };
+                props.onClick.call(undefined, ev);
+            }
+        },
+        [props.onClick, dispatchStateValue, value]
+    );
+
+    const handleKeyDown = React.useCallback(
+        (syntheticEvent: React.KeyboardEvent) => {
+            if (readonly || disabled) {
+                return;
+            }
+            switch (syntheticEvent.keyCode) {
+                case Keys.right:
+                    syntheticEvent.preventDefault();
+                    dispatchStateValue({
+                        type: dir === 'rtl' ? RATING_ACTION.decrease : RATING_ACTION.increase, event: syntheticEvent
+                    });
+                    break;
+                case Keys.left:
+                    syntheticEvent.preventDefault();
+                    dispatchStateValue({
+                        type: dir === 'rtl' ? RATING_ACTION.increase : RATING_ACTION.decrease, event: syntheticEvent
+                    });
+                    break;
+                case Keys.home:
+                    syntheticEvent.preventDefault();
+                    dispatchStateValue({
+                        type: dir === 'rtl' ? RATING_ACTION.min : RATING_ACTION.max, event: syntheticEvent
+                    });
+                    break;
+                case Keys.end:
+                    syntheticEvent.preventDefault();
+                    dispatchStateValue({
+                        type: dir === 'rtl' ? RATING_ACTION.max : RATING_ACTION.min, event: syntheticEvent
+                    });
+                    break;
+                case Keys.esc:
+                    syntheticEvent.preventDefault();
+                    dispatchStateValue({
+                        type: RATING_ACTION.deselect, event: syntheticEvent
+                    });
+                    break;
+                default:
+                    break;
+            }
+
+            if (props.onKeyDown) {
+                props.onKeyDown.call(
+                    undefined,
+                    {
+                        value,
+                        target: target.current,
+                        syntheticEvent
+                    } as RatingKeyboardEvent);
+            }
+        },
+        [props.onKeyDown, dispatchStateValue, value]
+    );
+
+    const handleFocus = React.useCallback(
+        (syntheticEvent: React.FocusEvent) => {
+            if (props.onFocus) {
+                const ev: RatingItemFocusEvent = {
+                    target: target.current as any,
+                    syntheticEvent
+                };
+                props.onFocus.call(
+                    undefined,
+                    ev);
+            }
+        },
+        [props.onFocus]
+    );
+
+    const handleBlur = React.useCallback(
+        (syntheticEvent: React.FocusEvent) => {
+            if (props.onBlur) {
+                const ev: RatingItemFocusEvent = {
+                    target: target.current as any,
+                    syntheticEvent
+                };
+                props.onBlur.call(
+                    undefined,
+                    ev);
+            }
+        },
+        [props.onBlur]
+    );
+
+    const handleItemMouseMove = React.useCallback(
+        (event: RatingItemMouseEvent) => {
+            if (!event.target || !event.target.element) {
+                return;
+            }
+            if (precision === 'half') {
+                const rect = event.target.element.getBoundingClientRect();
+                const isFirstHalf = calcIsFirstHalf(dir ? dir : 'ltr', rect, event.syntheticEvent.clientX);
+                const payload = isFirstHalf ? event.target.value - (step / 2) : event.target.value;
+
+                dispatchStateHover({ type: RATING_ACTION.select, payload, event: event.syntheticEvent });
+            } else {
+                dispatchStateHover({ type: RATING_ACTION.select, payload: event.target.value, event: event.syntheticEvent });
+            }
+        },
+        [precision, step, dir]
+    );
+
+    const handleMouseLeave = React.useCallback(
+        (event: RatingItemMouseEvent) => {
+            dispatchStateHover({ type: RATING_ACTION.reset, event: event.syntheticEvent });
+        },
+        []
+    );
+
+    const items: any[] = [];
+    const remainder = getRemainder(toRound(max - min, base), step);
+    for (let i = min; i <= max; i = toRound(i + step, base)) {
+        const itemValue = toRound(i + remainder, base);
+        const half = precision === 'half'
+            ? isHalf(itemValue, hoveredValue !== null ? hoveredValue : (value !== null ? value : 0), step)
+            : false;
+        const selectedValue = isSelected(itemValue, value, step, selection);
+        const selected = isSelected(itemValue, hoveredValue !== null ? hoveredValue : value, step, selection);
+        const hovered = isSelected(itemValue, hoveredValue, step, selection);
+
+        items.push(
+          <Item
+            key={itemValue}
+            value={itemValue}
+            dir={dir}
+            title={String(half ? toRound(itemValue - (step / 2), base) : itemValue)}
+            icon={props.icon}
+            half={half}
+            selected={selectedValue || selected}
+            hovered={hovered}
+            onClick={handleItemClick}
+            onMouseMove={handleItemMouseMove}
+            onMouseLeave={handleMouseLeave}
+            >
+            {half && (
+            <span
+              className={'k-rating-precision-complement'}
+              style={{ width: '12px', [dir === 'rtl' ? 'right' : 'left']: '50%' }}
+                    >
+              <span
+                className={classNames(
+                                'k-icon',
+                                {
+                                    'k-i-star-outline': !props.icon,
+                                    [`${props.icon}-outline`]: props.icon
+                                }
+                            )}
+                        />
+            </span>
+                )}
+            {half && (
+            <span
+              className={'k-rating-precision-part'}
+              style={{ width: '12px' }}
+                    >
+              <span
+                className={classNames(
+                                'k-icon',
+                                {
+                                    'k-i-star': !props.icon,
+                                    [`${props.icon}`]: props.icon
+                                }
+                            )}
+                        />
+            </span>)
+                }
+            {half && (
+            <span style={{ width: '24px', height: '24px', display: 'block' }} />
+                )}
+            {!half && (
+            <span
+              className={classNames(
+                            'k-icon',
+                            {
+                                'k-i-star': !props.icon && (hovered || (selected && !hovered)),
+                                'k-i-star-outline': !props.icon && (!hovered),
+                                [`${props.icon}`]: props.icon && (hovered || (selected && !hovered)),
+                                [`${props.icon}-outline`]: props.icon && (!hovered)
+                            }
+                        )}
+                    />
+                )}
+          </Item>
+        );
+    }
+
+    return (
+      <span
+        id={props.id}
+        style={props.style}
+        ref={ratingRef}
+        role="slider"
+        dir={dir}
+        tabIndex={getTabIndex(props.tabIndex, props.disabled, undefined)}
+        className={classNames(
+                'k-rating k-widget',
+                {
+                    'k-rtl': dir === 'rtl',
+                    'k-state-readonly': readonly,
+                    'k-disabled': disabled
+                },
+                props.className
+            )}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={value !== null ? value : undefined}
+        aria-disabled={disabled ? 'true' : undefined}
+        aria-label={localization.toLanguageString(ratingAriaLabel, messages[ratingAriaLabel])}
+        aria-labelledby={props.ariaLabelledBy}
+        aria-describedby={props.ariaDescribedBy}
+        >
+        <input
+          id={'rating'}
+          className={'k-hidden'}
+          readOnly={readonly}
+          disabled={disabled}
+            />
+        <span
+          className={'k-rating-container'}
+            >
+          {items}
+        </span>
+        {props.label &&
+        <span
+          className={'k-rating-label'}
+                >
+          {props.label}
+        </span>
+            }
+      </span>
+    );
+});
+
+const propTypes = {
+    id: PropTypes.string,
+    dir: PropTypes.oneOf(['ltr', 'rtl']),
+    selection: PropTypes.oneOf(['continues', 'single']),
+    precision: PropTypes.oneOf(['item', 'half']),
+    value: (props: RatingProps, propName: string, componentName: string) => {
+        if (props.value && props.min && props.max && props.step) {
+            const correctValue = props.precision === 'half'
+                ? isCorrectValue(props.min, props.max, props.step / 2, props.value)
+                : isCorrectValue(props.min, props.max, props.step, props.value);
+            if (!correctValue && props.precision === 'half') {
+                return new Error(
+                    `Invalid prop + ${propName} supplied to ${componentName}.
+                    The value of the { value } property is not correct, please check your values.
+                    `
+                );
+            }
+        }
+        return null;
+    },
+    defaultValue: PropTypes.number,
+    min: PropTypes.number,
+    max: PropTypes.number,
+    step: (props: RatingProps, propName: string, componentName: string) => {
+        if (props.step !== undefined && props.step <= 0) {
+            return new Error(
+                `Invalid prop + ${propName} supplied to ${componentName}.
+                The value of the { step } property is cannot be equal or less than "0", please check your values.
+                `
+            );
+        }
+        return null;
+    },
+    hovered: PropTypes.number,
+    label: PropTypes.string,
+    readonly: PropTypes.bool,
+    disabled: PropTypes.bool,
+    half: PropTypes.bool,
+    icon: PropTypes.string,
+    ariaDescribedBy: PropTypes.string
+
+};
+
+const defaultProps: any = {
+    dir: 'ltr',
+    min: 1,
+    max: 5,
+    step: 1,
+    item: RatingItem,
+    defaultValue: null,
+    readonly: false,
+    disabled: false,
+    selection: 'continues',
+    precision: 'item'
+};
+
+Rating.displayName = 'KendoReactRating';
+// TODO: delete casting when @types/react is updated!
+(Rating as any).propTypes = propTypes;
+Rating.defaultProps = defaultProps;