@tanstack/react-query-devtools 4.10.4 → 4.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-query-devtools",
-  "version": "4.10.4",
-  "description": "TODO",
+  "version": "4.12.0",
+  "description": "Developer tools to interact with and visualize the TanStack/react-query cache",
   "author": "tannerlinsley",
   "license": "MIT",
   "repository": "tanstack/query",
@@ -38,9 +38,15 @@
     "src"
   ],
   "devDependencies": {
+    "@types/react": "^18.0.14",
+    "@types/react-dom": "^18.0.5",
     "@types/use-sync-external-store": "^0.0.3",
+    "react": "^18.2.0",
+    "react-17": "npm:react@^17.0.2",
+    "react-dom": "^18.2.0",
+    "react-dom-17": "npm:react-dom@^17.0.2",
     "react-error-boundary": "^3.1.4",
-    "@tanstack/react-query": "4.10.3"
+    "@tanstack/react-query": "4.12.0"
   },
   "dependencies": {
     "@tanstack/match-sorter-utils": "^8.1.1",
@@ -50,10 +56,12 @@
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0",
-    "@tanstack/react-query": "4.10.3"
+    "@tanstack/react-query": "4.12.0"
   },
   "scripts": {
     "clean": "rm -rf ./build",
-    "test:eslint": "../../node_modules/.bin/eslint --ext .ts,.tsx ./src"
+    "test:eslint": "../../node_modules/.bin/eslint --ext .ts,.tsx ./src",
+    "test:jest": "../../node_modules/.bin/jest --config ./jest.config.ts",
+    "test:dev": "pnpm run test:jest --watch"
   }
 }

package/src/__tests__/devtools.test.tsx

@@ -764,4 +764,103 @@ describe('ReactQueryDevtools', () => {
       consoleErrorMock.mockRestore()
     })
   })
+
+  it('should render a menu to select panel position', async () => {
+    const { queryClient } = createQueryClient()
+
+    function Page() {
+      const { data = 'default' } = useQuery(['check'], async () => 'test')
+
+      return (
+        <div>
+          <h1>{data}</h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <Page />, {
+      initialIsOpen: true,
+    })
+
+    const positionSelect = (await screen.findByLabelText(
+      'Panel position',
+    )) as HTMLSelectElement
+
+    expect(positionSelect.value).toBe('bottom')
+  })
+
+  it(`should render the panel to the left if panelPosition is set to 'left'`, async () => {
+    const { queryClient } = createQueryClient()
+
+    function Page() {
+      const { data = 'default' } = useQuery(['check'], async () => 'test')
+
+      return (
+        <div>
+          <h1>{data}</h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <Page />, {
+      initialIsOpen: true,
+      panelPosition: 'left',
+    })
+
+    const positionSelect = (await screen.findByLabelText(
+      'Panel position',
+    )) as HTMLSelectElement
+
+    expect(positionSelect.value).toBe('left')
+
+    const panel = (await screen.getByLabelText(
+      'React Query Devtools Panel',
+    )) as HTMLDivElement
+
+    expect(panel.style.left).toBe('0px')
+    expect(panel.style.width).toBe('500px')
+    expect(panel.style.height).toBe('100vh')
+  })
+
+  it('should change the panel position if user select different option from the menu', async () => {
+    const { queryClient } = createQueryClient()
+
+    function Page() {
+      const { data = 'default' } = useQuery(['check'], async () => 'test')
+
+      return (
+        <div>
+          <h1>{data}</h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <Page />, {
+      initialIsOpen: true,
+    })
+
+    const positionSelect = (await screen.findByLabelText(
+      'Panel position',
+    )) as HTMLSelectElement
+
+    expect(positionSelect.value).toBe('bottom')
+
+    const panel = (await screen.getByLabelText(
+      'React Query Devtools Panel',
+    )) as HTMLDivElement
+
+    expect(panel.style.bottom).toBe('0px')
+    expect(panel.style.height).toBe('500px')
+    expect(panel.style.width).toBe('100%')
+
+    await act(async () => {
+      fireEvent.change(positionSelect, { target: { value: 'right' } })
+    })
+
+    expect(positionSelect.value).toBe('right')
+
+    expect(panel.style.right).toBe('0px')
+    expect(panel.style.width).toBe('500px')
+    expect(panel.style.height).toBe('100vh')
+  })
 })

package/src/devtools.tsx

@@ -13,9 +13,17 @@ import {
 } from '@tanstack/react-query'
 import { rankItem } from '@tanstack/match-sorter-utils'
 import useLocalStorage from './useLocalStorage'
-import { sortFns, useIsMounted } from './utils'
-import ScreenReader from './screenreader'
-
+import {
+  isVerticalSide,
+  sortFns,
+  useIsMounted,
+  getSidePanelStyle,
+  minPanelSize,
+  getResizeHandleStyle,
+  getSidedProp,
+  defaultPanelSize,
+} from './utils'
+import type { Corner, Side } from './utils'
 import {
   Panel,
   QueryKeys,
@@ -26,6 +34,7 @@ import {
   Select,
   ActiveQueryPanel,
 } from './styledComponents'
+import ScreenReader from './screenreader'
 import { ThemeProvider, defaultTheme as theme } from './theme'
 import { getQueryStatusLabel, getQueryStatusColor } from './utils'
 import Explorer from './Explorer'
@@ -39,29 +48,25 @@ export interface DevtoolsOptions extends ContextOptions {
   /**
    * Use this to add props to the panel. For example, you can add className, style (merge and override default style), etc.
    */
-  panelProps?: React.DetailedHTMLProps<
-    React.HTMLAttributes<HTMLDivElement>,
-    HTMLDivElement
-  >
+  panelProps?: React.ComponentPropsWithoutRef<'div'>
   /**
    * Use this to add props to the close button. For example, you can add className, style (merge and override default style), onClick (extend default handler), etc.
    */
-  closeButtonProps?: React.DetailedHTMLProps<
-    React.ButtonHTMLAttributes<HTMLButtonElement>,
-    HTMLButtonElement
-  >
+  closeButtonProps?: React.ComponentPropsWithoutRef<'button'>
   /**
    * Use this to add props to the toggle button. For example, you can add className, style (merge and override default style), onClick (extend default handler), etc.
    */
-  toggleButtonProps?: React.DetailedHTMLProps<
-    React.ButtonHTMLAttributes<HTMLButtonElement>,
-    HTMLButtonElement
-  >
+  toggleButtonProps?: React.ComponentPropsWithoutRef<'button'>
   /**
    * The position of the React Query logo to open and close the devtools panel.
    * Defaults to 'bottom-left'.
    */
-  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  position?: Corner
+  /**
+   * The position of the React Query devtools panel.
+   * Defaults to 'bottom'.
+   */
+  panelPosition?: Side
   /**
    * Use this to render the devtools inside a different type of container element for a11y purposes.
    * Any string which corresponds to a valid intrinsic JSX element is allowed.
@@ -98,7 +103,24 @@ interface DevtoolsPanelOptions extends ContextOptions {
   /**
    * Handles the opening and closing the devtools panel
    */
-  handleDragStart: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void
+  onDragStart: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void
+  /**
+   * The position of the React Query devtools panel.
+   * Defaults to 'bottom'.
+   */
+  position?: Side
+  /**
+   * Handles the panel position select change
+   */
+  onPositionChange?: (side: Side) => void
+  /**
+   * Show a close button inside the panel
+   */
+  showCloseButton?: boolean
+  /**
+   * Use this to add props to the close button. For example, you can add className, style (merge and override default style), onClick (extend default handler), etc.
+   */
+  closeButtonProps?: React.ComponentPropsWithoutRef<'button'>
 }
 
 export function ReactQueryDevtools({
@@ -110,6 +132,7 @@ export function ReactQueryDevtools({
   containerElement: Container = 'aside',
   context,
   styleNonce,
+  panelPosition: initialPanelPosition = 'bottom',
 }: DevtoolsOptions): React.ReactElement | null {
   const rootRef = React.useRef<HTMLDivElement>(null)
   const panelRef = React.useRef<HTMLDivElement>(null)
@@ -117,10 +140,20 @@ export function ReactQueryDevtools({
     'reactQueryDevtoolsOpen',
     initialIsOpen,
   )
-  const [devtoolsHeight, setDevtoolsHeight] = useLocalStorage<number | null>(
+  const [devtoolsHeight, setDevtoolsHeight] = useLocalStorage<number>(
     'reactQueryDevtoolsHeight',
-    null,
+    defaultPanelSize,
+  )
+  const [devtoolsWidth, setDevtoolsWidth] = useLocalStorage<number>(
+    'reactQueryDevtoolsWidth',
+    defaultPanelSize,
+  )
+
+  const [panelPosition = 'bottom', setPanelPosition] = useLocalStorage<Side>(
+    'reactQueryDevtoolsPanelPosition',
+    initialPanelPosition,
   )
+
   const [isResolvedOpen, setIsResolvedOpen] = React.useState(false)
   const [isResizing, setIsResizing] = React.useState(false)
   const isMounted = useIsMounted()
@@ -129,22 +162,39 @@ export function ReactQueryDevtools({
     panelElement: HTMLDivElement | null,
     startEvent: React.MouseEvent<HTMLDivElement, MouseEvent>,
   ) => {
+    if (!panelElement) return
     if (startEvent.button !== 0) return // Only allow left click for drag
-
+    const isVertical = isVerticalSide(panelPosition)
     setIsResizing(true)
 
-    const dragInfo = {
-      originalHeight: panelElement?.getBoundingClientRect().height ?? 0,
-      pageY: startEvent.pageY,
-    }
+    const { height, width } = panelElement.getBoundingClientRect()
+    const startX = startEvent.clientX
+    const startY = startEvent.clientY
+    let newSize = 0
 
     const run = (moveEvent: MouseEvent) => {
-      const delta = dragInfo.pageY - moveEvent.pageY
-      const newHeight = dragInfo.originalHeight + delta
-
-      setDevtoolsHeight(newHeight)
+      // prevent mouse selecting stuff with mouse drag
+      moveEvent.preventDefault()
+
+      // calculate the correct size based on mouse position and current panel position
+      // hint: it is different formula for the opposite sides
+      if (isVertical) {
+        newSize =
+          width +
+          (panelPosition === 'right'
+            ? startX - moveEvent.clientX
+            : moveEvent.clientX - startX)
+        setDevtoolsWidth(newSize)
+      } else {
+        newSize =
+          height +
+          (panelPosition === 'bottom'
+            ? startY - moveEvent.clientY
+            : moveEvent.clientY - startY)
+        setDevtoolsHeight(newSize)
+      }
 
-      if (newHeight < 70) {
+      if (newSize < minPanelSize) {
         setIsOpen(false)
       } else {
         setIsOpen(true)
@@ -152,13 +202,16 @@ export function ReactQueryDevtools({
     }
 
     const unsub = () => {
-      setIsResizing(false)
-      document.removeEventListener('mousemove', run)
-      document.removeEventListener('mouseUp', unsub)
+      if (isResizing) {
+        setIsResizing(false)
+      }
+
+      document.removeEventListener('mousemove', run, false)
+      document.removeEventListener('mouseUp', unsub, false)
     }
 
-    document.addEventListener('mousemove', run)
-    document.addEventListener('mouseup', unsub)
+    document.addEventListener('mousemove', run, false)
+    document.addEventListener('mouseup', unsub, false)
   }
 
   React.useEffect(() => {
@@ -195,12 +248,23 @@ export function ReactQueryDevtools({
   React.useEffect(() => {
     if (isResolvedOpen) {
       const root = rootRef.current
-      const previousValue = root?.parentElement?.style.paddingBottom
+      const styleProp = getSidedProp('padding', panelPosition)
+      const isVertical = isVerticalSide(panelPosition)
+      const previousValue = root?.parentElement?.style[styleProp]
 
       const run = () => {
-        const containerHeight = panelRef.current?.getBoundingClientRect().height
         if (root?.parentElement) {
-          root.parentElement.style.paddingBottom = `${containerHeight}px`
+          // reset the padding
+          root.parentElement.style.padding = '0px'
+          root.parentElement.style.paddingTop = '0px'
+          root.parentElement.style.paddingBottom = '0px'
+          root.parentElement.style.paddingLeft = '0px'
+          root.parentElement.style.paddingRight = '0px'
+          // set the new padding based on the new panel position
+
+          root.parentElement.style[styleProp] = `${
+            isVertical ? devtoolsWidth : devtoolsHeight
+          }px`
         }
       }
 
@@ -212,27 +276,32 @@ export function ReactQueryDevtools({
         return () => {
           window.removeEventListener('resize', run)
           if (root?.parentElement && typeof previousValue === 'string') {
-            root.parentElement.style.paddingBottom = previousValue
+            root.parentElement.style[styleProp] = previousValue
           }
         }
       }
     }
-  }, [isResolvedOpen])
+  }, [isResolvedOpen, panelPosition, devtoolsHeight, devtoolsWidth])
 
   const { style: panelStyle = {}, ...otherPanelProps } = panelProps
 
-  const {
-    style: closeButtonStyle = {},
-    onClick: onCloseClick,
-    ...otherCloseButtonProps
-  } = closeButtonProps
-
   const {
     style: toggleButtonStyle = {},
     onClick: onToggleClick,
     ...otherToggleButtonProps
   } = toggleButtonProps
 
+  // get computed style based on panel position
+  const style = getSidePanelStyle({
+    position: panelPosition,
+    devtoolsTheme: theme,
+    isOpen: isResolvedOpen,
+    height: devtoolsHeight,
+    width: devtoolsWidth,
+    isResizing,
+    panelStyle,
+  })
+
   // Do not render on the server
   if (!isMounted()) return null
 
@@ -247,80 +316,16 @@ export function ReactQueryDevtools({
           ref={panelRef as any}
           context={context}
           styleNonce={styleNonce}
+          position={panelPosition}
+          onPositionChange={setPanelPosition}
+          showCloseButton
+          closeButtonProps={closeButtonProps}
           {...otherPanelProps}
-          style={{
-            direction: 'ltr',
-            position: 'fixed',
-            bottom: '0',
-            right: '0',
-            zIndex: 99999,
-            width: '100%',
-            height: devtoolsHeight ?? 500,
-            maxHeight: '90%',
-            boxShadow: '0 0 20px rgba(0,0,0,.3)',
-            borderTop: `1px solid ${theme.gray}`,
-            transformOrigin: 'top',
-            // visibility will be toggled after transitions, but set initial state here
-            visibility: isOpen ? 'visible' : 'hidden',
-            ...panelStyle,
-            ...(isResizing
-              ? {
-                  transition: `none`,
-                }
-              : { transition: `all .2s ease` }),
-            ...(isResolvedOpen
-              ? {
-                  opacity: 1,
-                  pointerEvents: 'all',
-                  transform: `translateY(0) scale(1)`,
-                }
-              : {
-                  opacity: 0,
-                  pointerEvents: 'none',
-                  transform: `translateY(15px) scale(1.02)`,
-                }),
-          }}
+          style={style}
           isOpen={isResolvedOpen}
           setIsOpen={setIsOpen}
-          handleDragStart={(e) => handleDragStart(panelRef.current, e)}
+          onDragStart={(e) => handleDragStart(panelRef.current, e)}
         />
-        {isResolvedOpen ? (
-          <Button
-            type="button"
-            aria-controls="ReactQueryDevtoolsPanel"
-            aria-haspopup="true"
-            aria-expanded="true"
-            {...(otherCloseButtonProps as Record<string, unknown>)}
-            onClick={(e) => {
-              setIsOpen(false)
-              onCloseClick?.(e)
-            }}
-            style={{
-              position: 'fixed',
-              zIndex: 99999,
-              margin: '.5em',
-              bottom: 0,
-              ...(position === 'top-right'
-                ? {
-                    right: '0',
-                  }
-                : position === 'top-left'
-                ? {
-                    left: '0',
-                  }
-                : position === 'bottom-right'
-                ? {
-                    right: '0',
-                  }
-                : {
-                    left: '0',
-                  }),
-              ...closeButtonStyle,
-            }}
-          >
-            Close
-          </Button>
-        ) : null}
       </ThemeProvider>
       {!isResolvedOpen ? (
         <button
@@ -404,11 +409,17 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
     isOpen = true,
     styleNonce,
     setIsOpen,
-    handleDragStart,
     context,
+    onDragStart,
+    onPositionChange,
+    showCloseButton,
+    position,
+    closeButtonProps = {},
     ...panelProps
   } = props
 
+  const { onClick: onCloseClick, ...otherCloseButtonProps } = closeButtonProps
+
   const queryClient = useQueryClient({ context })
   const queryCache = queryClient.getQueryCache()
 
@@ -467,6 +478,11 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
         aria-label="React Query Devtools Panel"
         id="ReactQueryDevtoolsPanel"
         {...panelProps}
+        style={{
+          height: defaultPanelSize,
+          position: 'relative',
+          ...panelProps.style,
+        }}
       >
         <style
           nonce={styleNonce}
@@ -494,17 +510,8 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
           }}
         />
         <div
-          style={{
-            position: 'absolute',
-            left: 0,
-            top: 0,
-            width: '100%',
-            height: '4px',
-            marginBottom: '-4px',
-            cursor: 'row-resize',
-            zIndex: 100000,
-          }}
-          onMouseDown={handleDragStart}
+          style={getResizeHandleStyle(position)}
+          onMouseDown={onDragStart}
         ></div>
 
         {isOpen && (
@@ -553,7 +560,29 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
                   flexDirection: 'column',
                 }}
               >
-                <QueryStatusCount queryCache={queryCache} />
+                <div
+                  style={{
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    marginBottom: '.5em',
+                  }}
+                >
+                  <QueryStatusCount queryCache={queryCache} />
+                  {position && onPositionChange ? (
+                    <Select
+                      aria-label="Panel position"
+                      value={position}
+                      style={{ marginInlineStart: '.5em' }}
+                      onChange={(e) => onPositionChange(e.target.value as Side)}
+                    >
+                      <option value="left">Left</option>
+                      <option value="right">Right</option>
+                      <option value="top">Top</option>
+                      <option value="bottom">Bottom</option>
+                    </Select>
+                  ) : null}
+                </div>
                 <div
                   style={{
                     display: 'flex',
@@ -705,6 +734,30 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
             queryClient={queryClient}
           />
         ) : null}
+
+        {showCloseButton ? (
+          <Button
+            type="button"
+            aria-controls="ReactQueryDevtoolsPanel"
+            aria-haspopup="true"
+            aria-expanded="true"
+            {...(otherCloseButtonProps as Record<string, unknown>)}
+            style={{
+              position: 'absolute',
+              zIndex: 99999,
+              margin: '.5em',
+              bottom: 0,
+              left: 0,
+              ...otherCloseButtonProps.style,
+            }}
+            onClick={(e) => {
+              setIsOpen(false)
+              onCloseClick?.(e)
+            }}
+          >
+            Close
+          </Button>
+        ) : null}
       </Panel>
     </ThemeProvider>
   )
@@ -974,7 +1027,7 @@ const QueryStatusCount = ({ queryCache }: { queryCache: QueryCache }) => {
         .length,
   )
   return (
-    <QueryKeys style={{ marginBottom: '.5em' }}>
+    <QueryKeys>
       <QueryKey
         style={{
           background: theme.success,