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

package/src/signature/Signature.tsx

@@ -0,0 +1,488 @@
+import { Button } from '@progress/kendo-react-buttons';
+import { Dialog } from '@progress/kendo-react-dialogs';
+import {
+    classNames,
+    createPropsContext,
+    dispatchEvent,
+    getTabIndex,
+    kendoThemeMaps,
+    noop,
+    usePropsContext
+} from '@progress/kendo-react-common';
+
+import { validatePackage } from '@progress/kendo-react-common';
+import { useLocalization } from '@progress/kendo-react-intl';
+import * as PropTypes from 'prop-types';
+import * as React from 'react';
+import { messages, signatureClear, signatureMaximize, signatureMinimize } from '../messages';
+import { packageMetadata } from '../package-metadata';
+import { SignatureBlurEvent } from './interfaces/SignatureBlurEvent';
+import { SignatureChangeEvent } from './interfaces/SignatureChangeEvent';
+import { SignatureFocusEvent } from './interfaces/SignatureFocusEvent';
+import { SignatureOpenEvent } from './interfaces/SignatureOpenEvent';
+import { SignatureCloseEvent } from './interfaces/SignatureCloseEvent';
+import { SignatureHandle } from './interfaces/SignatureHandle';
+import { SignatureProps } from './interfaces/SignatureProps';
+import { SignaturePad } from '@progress/kendo-inputs-common';
+import { hasParent } from './utils';
+
+const DEFAULT_WIDTH = 250;
+const DEFAULT_HEIGHT = 84;
+const DEFAULT_POPUP_SCALE = 3;
+const DEFAULT_EXPORT_SCALE = 2;
+
+/**
+ * @hidden
+ */
+const isControlled = (prop: any): boolean => {
+    return prop !== undefined;
+};
+
+/**
+ * Represents the PropsContext of the `Signature` component.
+ * Used for global configuration of all `Signature` instances.
+ *
+ * For more information, refer to the [Inputs Props Context]({% slug props-context_inputs %}) article.
+ */
+export const SignaturePropsContext = createPropsContext<SignatureProps>();
+
+/**
+ * Represents the [KendoReact Signature component]({% slug overview_signature %}).
+ */
+export const Signature = React.forwardRef<SignatureHandle | null, SignatureProps>((directProps, target) => {
+    validatePackage(packageMetadata);
+
+    const props = usePropsContext(SignaturePropsContext, directProps);
+    const localizationService = useLocalization();
+    const elementRef = React.useRef<HTMLDivElement>(null);
+    const canvasRef = React.useRef<HTMLDivElement>(null);
+    const dialogRef = React.useRef<Dialog>(null);
+
+    const [instance, setInstance] = React.useState<SignaturePad>();
+    const [focused, setFocused] = React.useState(false);
+    const [isDrawing, setIsDrawing] = React.useState(false);
+
+    const [stateValue, setStateValue] = React.useState<string>();
+    const [popupValue, setPopupValue] = React.useState<string>();
+    const isValueControlled = isControlled(props.value);
+    const value = isValueControlled ? props.value : stateValue;
+
+    const [stateOpen, setStateOpen] = React.useState(false);
+    const isOpenControlled = isControlled(props.open);
+    const open = isOpenControlled ? props.open! : stateOpen;
+
+    const showMaximize = !(props.maximized || isDrawing || !props.maximizable || props.disabled);
+    const showMinimize = props.maximized && !isDrawing;
+    const isEmpty = !(props.value || stateValue);
+    const showClear = !(isEmpty || isDrawing || props.readOnly || props.disabled);
+
+    const maximizeTitle = localizationService.toLanguageString(signatureMaximize, messages[signatureMaximize]);
+    const minimizeTitle = localizationService.toLanguageString(signatureMinimize, messages[signatureMinimize]);
+    const clearTitle = localizationService.toLanguageString(signatureClear, messages[signatureClear]);
+
+    const onValueChange = (nextValue?: string) => {
+        setStateValue(nextValue);
+
+        if (props.onChange) {
+            props.onChange({ value: nextValue } as SignatureChangeEvent);
+        }
+    };
+
+    const onDialogChange = (e: SignatureChangeEvent) => {
+        instance?.loadImage(e.value);
+        onValueChange(e.value);
+    };
+
+    React.useEffect(() => {
+        if (props.value !== stateValue) {
+            setStateValue(props.value);
+            instance?.loadImage(props.value!);
+        }
+    }, [props.value]);
+
+    const reset = () => {
+        instance?.clear();
+        onValueChange();
+    };
+
+    const setOpen = React.useCallback(
+        (nextOpen: boolean) => {
+            if (!isOpenControlled) {
+                setStateOpen(nextOpen);
+            }
+        },
+        [isOpenControlled]
+    );
+
+    const onDialogClose = (event: any) => {
+        onMinimizeClick(event);
+        focusElement();
+    };
+
+    const getOptions = () => ({
+        scale: props.maximized ? props.popupScale : 1,
+        color: props.color,
+        backgroundColor: props.backgroundColor,
+        strokeWidth: props.strokeWidth,
+        smooth: props.smooth,
+        readonly: props.readOnly
+    });
+
+    const exportImage = async(exportSize: {width: number; height: number}) => {
+        const {width, height} = exportSize;
+        return await instance?.exportImage({
+            width: width * (props.exportScale || DEFAULT_EXPORT_SCALE),
+            height: height * (props.exportScale || DEFAULT_EXPORT_SCALE)
+        });
+    };
+
+    React.useEffect(() => {
+        const canvas = canvasRef.current as HTMLElement;
+        const pad: SignaturePad = new SignaturePad(canvas, getOptions());
+
+        if (value) {
+            pad.loadImage(value);
+        }
+
+        setInstance(pad);
+
+        return () => pad.destroy();
+    }, []);
+
+    React.useEffect(() => {
+        instance?.setOptions({
+            onChange: async() => onValueChange(await exportImage(elementSize())),
+            onDraw: () => setIsDrawing(true),
+            onDrawEnd: () => setIsDrawing(false)
+        });
+    }, [instance]);
+
+    React.useLayoutEffect(
+        () => instance?.setOptions(getOptions()),
+        [props.readOnly, props.color, props.backgroundColor, props.strokeWidth, props.smooth]
+    );
+
+    React.useEffect(() => {
+        const overlay = dialogRef.current?.element?.querySelector('.k-overlay');
+        if (!overlay) {
+            return;
+        }
+
+        const onOverlayClick = () => setOpen(false);
+        overlay.addEventListener('click', onOverlayClick);
+
+        return () => {
+            return overlay.removeEventListener('click', onOverlayClick);
+        };
+    }, [open]);
+
+    const focusElement = React.useCallback(
+        () => canvasRef.current?.focus(),
+        []
+    );
+
+    const valueGetter = React.useCallback(
+        () => props.value,
+        [props.value]
+    );
+
+    const nameGetter = React.useCallback(
+        () => props.name,
+        [props.name]
+    );
+
+    const requiredGetter = React.useCallback(
+        () => props.required,
+        [props.required]
+    );
+
+    const validityGetter = React.useCallback(
+        () => {
+            const customError = props.validationMessage !== undefined;
+            const currentValue = valueGetter();
+            const valueMissing = !currentValue;
+
+            const valid = props.valid !== undefined ?
+                props.valid :
+                (!requiredGetter() || !valueMissing);
+
+            return {
+                customError,
+                valid,
+                valueMissing
+            };
+        },
+        [props.validationMessage, props.valid, valueGetter, requiredGetter]
+    );
+
+    const validityStylesGetter = React.useCallback(
+        () => {
+            return props.validityStyles;
+        },
+        [props.validityStyles]
+    );
+
+    const propsGetter = React.useCallback(
+        () => {
+            return props;
+        },
+        [props]
+    );
+
+    const getImperativeHandle = React.useCallback(
+        (): SignatureHandle => {
+            const options = {
+                element: elementRef.current,
+                focus: focusElement
+            };
+
+            Object.defineProperty(options, 'name', { get: nameGetter });
+            Object.defineProperty(options, 'value', { get: valueGetter });
+            Object.defineProperty(options, 'validity', { get: validityGetter });
+            Object.defineProperty(options, 'validityStyles', { get: validityStylesGetter });
+            Object.defineProperty(options, 'required', { get: requiredGetter });
+            Object.defineProperty(options, 'props', { get: propsGetter });
+
+            return options as SignatureHandle;
+        },
+        [nameGetter, valueGetter, validityGetter, validityStylesGetter, requiredGetter, focusElement, propsGetter]
+    );
+
+    React.useImperativeHandle(target, getImperativeHandle);
+
+    const onFocus = React.useCallback(
+        (event: any) => {
+            if (focused || props.maximized) {
+                return;
+            }
+
+            setFocused(true);
+
+            dispatchEvent<any, SignatureHandle>(
+                props.onFocus,
+                event,
+                getImperativeHandle(),
+                {}
+            );
+        },
+        [focused, props.onFocus, getImperativeHandle]
+    );
+
+
+    const onBlur = React.useCallback(
+        (event: any) => {
+            const insideWrapper = hasParent(event.relatedTarget, elementRef.current);
+            if (insideWrapper) {
+                return;
+            }
+
+            setFocused(false);
+
+            dispatchEvent<any, SignatureHandle>(
+                props.onBlur,
+                event,
+                getImperativeHandle(),
+                {}
+            );
+        },
+        [focused, props.onBlur, getImperativeHandle]
+    );
+
+    const onMaximizeClick = React.useCallback(
+        async (event: any) => {
+            setPopupValue(await exportImage(popupSize()));
+            setOpen(true);
+
+            dispatchEvent<any, SignatureHandle>(
+                props.onOpen,
+                event,
+                getImperativeHandle(),
+                {}
+            );
+        },
+        [open, isOpenControlled, props.onOpen, props.value, stateValue, getImperativeHandle]
+    );
+
+    const onMinimizeClick = React.useCallback(
+        (event: any) => {
+            setOpen(false);
+
+            dispatchEvent<any, SignatureHandle>(
+                props.onClose,
+                event,
+                getImperativeHandle(),
+                {}
+            );
+        },
+        [open, isOpenControlled, props.onClose, getImperativeHandle]
+    );
+
+    const onClear = () => {
+        reset();
+        focusElement();
+    };
+
+    const elementSize = () => {
+        const width = props.width || elementRef.current?.offsetWidth || DEFAULT_WIDTH;
+        const height = props.height || elementRef.current?.offsetHeight || DEFAULT_HEIGHT;
+
+        return {
+            width,
+            height
+        };
+    };
+
+    const popupSize = () => {
+        const {width, height} = elementSize();
+        const popupScale = props.popupScale || DEFAULT_POPUP_SCALE;
+
+        return {
+            width: width * popupScale,
+            height: height * popupScale
+        };
+    };
+
+    const isValid = !validityStylesGetter() || validityGetter().valid;
+
+    return (
+      <div
+        ref={elementRef}
+        dir={props.dir}
+        style={{ width: props.width, height: props.height, ...props.style }}
+        className={classNames(
+            'k-input',
+            'k-signature',
+            {
+                'k-signature-maximized': props.maximized,
+                [`k-signature-${kendoThemeMaps.sizeMap[props.size!] || props.size}`]: props.size,
+                [`k-signature-${props.fillMode}`]: props.fillMode,
+                [`k-rounded-${kendoThemeMaps.roundedMap[props.rounded!] || props.rounded}`]: props.rounded,
+                'k-invalid': !isValid,
+                'k-required': props.required,
+                'k-disabled': props.disabled,
+                'k-focus': focused
+            },
+            props.className
+        )}
+        aria-disabled={props.disabled ? 'true' : undefined}
+        onFocus={onFocus}
+        onBlur={onBlur}
+      >
+        <div className='k-signature-actions k-signature-actions-top'>
+          {showMaximize && (
+            <Button
+              className='k-signature-action k-signature-maximize'
+              icon='hyperlink-open'
+              shape={null}
+              fillMode='flat'
+              size={props.size}
+              onClick={onMaximizeClick}
+              aria-label={maximizeTitle}
+              title={maximizeTitle}
+                />
+            )}
+          {showMinimize && (
+            <Button
+              className='k-signature-action k-signature-minimize'
+              icon='window-minimize'
+              shape={null}
+              fillMode='flat'
+              size={props.size}
+              onClick={onMinimizeClick}
+              aria-label={minimizeTitle}
+              title={minimizeTitle}
+                />
+            )}
+        </div>
+
+        <div
+          className='k-signature-canvas'
+          tabIndex={getTabIndex(props.tabIndex, props.disabled)}
+          ref={canvasRef}
+         />
+
+        { !props.hideLine && (
+        <div
+          className='k-signature-line'
+          style={{ zIndex: 2, pointerEvents: 'none' }}
+        />
+        )}
+
+        <div className='k-signature-actions k-signature-actions-bottom'>
+          {showClear && (
+            <Button
+              className='k-signature-action k-signature-clear'
+              icon='close'
+              shape={null}
+              fillMode='flat'
+              size={props.size}
+              onClick={onClear}
+              aria-label={clearTitle}
+              title={clearTitle}
+                />
+            )}
+        </div>
+
+        { open && (
+        <Dialog ref={dialogRef}>
+          <Signature
+            {...props}
+            {...popupSize()}
+            value={popupValue}
+            maximized={true}
+            open={false}
+            onChange={onDialogChange}
+            onClose={onDialogClose}
+                    />
+        </Dialog>
+        )}
+      </div>
+    );
+});
+
+(Signature as React.ComponentType).propTypes = {
+    value: PropTypes.string,
+    width: PropTypes.number,
+    height: PropTypes.number,
+    tabIndex: PropTypes.number,
+    dir: PropTypes.string,
+    ariaDescribedBy: PropTypes.string,
+    ariaLabelledBy: PropTypes.string,
+    ariaLabel: PropTypes.string,
+    readOnly: PropTypes.bool,
+    disabled: PropTypes.bool,
+    validationMessage: PropTypes.string,
+    required: PropTypes.bool,
+
+    onChange: PropTypes.func,
+    onFocus: PropTypes.func,
+    onBlur: PropTypes.func,
+    onOpen: PropTypes.func,
+    onClose: PropTypes.func,
+
+    size: PropTypes.oneOf<SignatureProps['size']>([null, 'small', 'medium', 'large']),
+    rounded: PropTypes.oneOf<SignatureProps['rounded']>([null, 'small', 'medium', 'large', 'full']),
+    fillMode: PropTypes.oneOf<SignatureProps['fillMode']>([null, 'solid', 'flat', 'outline'])
+};
+
+Signature.displayName = 'KendoSignature';
+Signature.defaultProps = {
+    color: '#000000',
+    backgroundColor: '#ffffff',
+    strokeWidth: 1,
+    smooth: false,
+    popupScale: DEFAULT_POPUP_SCALE,
+    exportScale: DEFAULT_EXPORT_SCALE,
+    maximizable: true,
+    disabled: false,
+    required: false,
+    validityStyles: true,
+    onChange: (_: SignatureChangeEvent) => noop,
+    onFocus: (_: SignatureFocusEvent) => noop,
+    onBlur: (_: SignatureBlurEvent) => noop,
+    onOpen: (_: SignatureOpenEvent) => noop,
+    onClose: (_: SignatureCloseEvent) => noop,
+    size: 'medium' as SignatureProps['size'],
+    rounded: 'medium' as SignatureProps['rounded'],
+    fillMode: 'solid' as SignatureProps['fillMode']
+};

package/src/signature/interfaces/SignatureBlurEvent.tsx

@@ -0,0 +1,7 @@
+import { BaseEvent } from '@progress/kendo-react-common';
+import { SignatureHandle } from './SignatureHandle';
+
+/**
+ * The arguments for the `onBlur` Signature event.
+ */
+export interface SignatureBlurEvent extends BaseEvent<SignatureHandle> {}

package/src/signature/interfaces/SignatureChangeEvent.tsx

@@ -0,0 +1,12 @@
+import { BaseEvent } from '@progress/kendo-react-common';
+import { SignatureHandle } from './SignatureHandle';
+
+/**
+ * The arguments for the `change` event of the Signature.
+ */
+export interface SignatureChangeEvent extends BaseEvent<SignatureHandle> {
+    /**
+     * The current value of the Signature.
+     */
+    value: string;
+}

package/src/signature/interfaces/SignatureCloseEvent.tsx

@@ -0,0 +1,7 @@
+import { BaseEvent } from '@progress/kendo-react-common';
+import { SignatureHandle } from './SignatureHandle';
+
+/**
+ * The arguments for the `onClose` Signature event.
+ */
+export interface SignatureCloseEvent extends BaseEvent<SignatureHandle> {}

package/src/signature/interfaces/SignatureFocusEvent.tsx

@@ -0,0 +1,7 @@
+import { BaseEvent } from '@progress/kendo-react-common';
+import { SignatureHandle } from './SignatureHandle';
+
+/**
+ * The arguments for the `onFocus` Signature event.
+ */
+export interface SignatureFocusEvent extends BaseEvent<SignatureHandle> {}

package/src/signature/interfaces/SignatureHandle.tsx

@@ -0,0 +1,35 @@
+import { SignatureProps } from './SignatureProps';
+
+/**
+ * The Signature ref.
+ */
+export interface SignatureHandle {
+    /**
+     * The Signature element.
+     */
+    element: HTMLInputElement | null;
+    /**
+     * Focus the Signature.
+     */
+    focus: () => void;
+    /**
+     * Gets the `name` property of the Signature.
+     */
+    name: string | undefined;
+    /**
+     * Gets the value of the Signature.
+     */
+    value: number | null;
+    /**
+     * @hidden
+     */
+    props: SignatureProps;
+    /**
+     * @hidden
+     */
+    validityStyles: boolean;
+    /**
+     * @hidden
+     */
+    required: boolean;
+}

package/src/signature/interfaces/SignatureOpenEvent.tsx

@@ -0,0 +1,7 @@
+import { BaseEvent } from '@progress/kendo-react-common';
+import { SignatureHandle } from './SignatureHandle';
+
+/**
+ * The arguments for the `onOpen` Signature event.
+ */
+export interface SignatureOpenEvent extends BaseEvent<SignatureHandle> {}