From af0225db5db5014436dd176650bf74b9fb2d9dfd Mon Sep 17 00:00:00 2001 From: sarayourfriend Date: Thu, 11 Mar 2021 09:22:26 -0800 Subject: [PATCH 1/2] Components: Add types to Draggable --- packages/components/src/draggable/index.js | 37 +++++++++++++++++++--- packages/components/tsconfig.json | 1 + 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/packages/components/src/draggable/index.js b/packages/components/src/draggable/index.js index cefb6c7cec159..9c0a5236ff20a 100644 --- a/packages/components/src/draggable/index.js +++ b/packages/components/src/draggable/index.js @@ -9,6 +9,29 @@ const cloneHeightTransformationBreakpoint = 700; const clonePadding = 0; const bodyClass = 'is-dragging-components-draggable'; +/** + * @typedef RenderProp + * @property {(event: import('react').DragEvent) => void} onDraggableStart `onDragStart` handler. + * @property {(event: import('react').DragEvent) => void} onDraggableEnd `onDragEnd` handler. + */ + +/** + * @typedef Props + * @property {(props: RenderProp) => JSX.Element | null} children Children. + * @property {(event: import('react').DragEvent) => void} [onDragStart] Callback when dragging starts. + * @property {(event: import('react').DragEvent) => void} [onDragOver] Callback when dragging happens over ???. + * @property {(event: import('react').DragEvent) => void} [onDragEnd] Callback when dragging ends. + * @property {string} [cloneClassname] Classname for the cloned element. + * @property {string} [elementId] ID for the element. + * @property {any} [transferData] Transfer data for the drag event. + * @property {import('react').ReactNode} __experimentalDragComponent Component to show when dragging. + */ + +/** + * + * @param {Props} props + * @return {JSX.Element} A draggable component. + */ export default function Draggable( { children, onDragStart, @@ -19,19 +42,20 @@ export default function Draggable( { transferData, __experimentalDragComponent: dragComponent, } ) { - const dragComponentRef = useRef(); + /** @type {import('react').MutableRefObject} */ + const dragComponentRef = useRef( null ); const cleanup = useRef( () => {} ); /** * Removes the element clone, resets cursor, and removes drag listener. * - * @param {Object} event The non-custom DragEvent. + * @param {import('react').DragEvent} event The non-custom DragEvent. */ function end( event ) { event.preventDefault(); cleanup.current(); - if ( onDragOver ) { + if ( onDragEnd ) { onDragEnd( event ); } } @@ -44,9 +68,10 @@ export default function Draggable( { * - Sets transfer data. * - Adds dragover listener. * - * @param {Object} event The non-custom DragEvent. + * @param {import('react').DragEvent} event The non-custom DragEvent. */ function start( event ) { + // @ts-ignore We know that ownerDocument does exist on an Element const { ownerDocument } = event.target; event.dataTransfer.setData( 'text', JSON.stringify( transferData ) ); @@ -130,6 +155,9 @@ export default function Draggable( { let cursorLeft = event.clientX; let cursorTop = event.clientY; + /** + * @param {import('react').DragEvent} e + */ function over( e ) { cloneWrapper.style.top = `${ parseInt( cloneWrapper.style.top, 10 ) + e.clientY - cursorTop @@ -156,6 +184,7 @@ export default function Draggable( { // https://reactjs.org/docs/events.html#event-pooling event.persist(); + /** @type {number | undefined} */ let timerId; if ( onDragStart ) { diff --git a/packages/components/tsconfig.json b/packages/components/tsconfig.json index c6a77928f7d18..67c5fd1e856e8 100644 --- a/packages/components/tsconfig.json +++ b/packages/components/tsconfig.json @@ -17,6 +17,7 @@ "src/animate/**/*", "src/base-control/**/*", "src/dashicon/**/*", + "src/draggable/**/*", "src/flex/**/*", "src/form-group/**/*", "src/shortcut/**/*", From 2722dd5a1aec563b3980aa7605c9b896f1b1604d Mon Sep 17 00:00:00 2001 From: sarayourfriend Date: Fri, 12 Mar 2021 06:35:05 -0800 Subject: [PATCH 2/2] Fix onDragOver description --- packages/components/src/draggable/index.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/components/src/draggable/index.js b/packages/components/src/draggable/index.js index 9c0a5236ff20a..bb8b8fe68eed0 100644 --- a/packages/components/src/draggable/index.js +++ b/packages/components/src/draggable/index.js @@ -19,7 +19,7 @@ const bodyClass = 'is-dragging-components-draggable'; * @typedef Props * @property {(props: RenderProp) => JSX.Element | null} children Children. * @property {(event: import('react').DragEvent) => void} [onDragStart] Callback when dragging starts. - * @property {(event: import('react').DragEvent) => void} [onDragOver] Callback when dragging happens over ???. + * @property {(event: import('react').DragEvent) => void} [onDragOver] Callback when dragging happens over the document. * @property {(event: import('react').DragEvent) => void} [onDragEnd] Callback when dragging ends. * @property {string} [cloneClassname] Classname for the cloned element. * @property {string} [elementId] ID for the element. @@ -28,7 +28,6 @@ const bodyClass = 'is-dragging-components-draggable'; */ /** - * * @param {Props} props * @return {JSX.Element} A draggable component. */