use-move-note.ts

Overview

The use-move-note.ts file defines a custom React hook named useMoveNote. This hook facilitates the dynamic positioning and visibility control of an SVG element (typically used as a note or tooltip) relative to the user's mouse cursor. It leverages the useMouse hook from the ahooks library to track mouse coordinates and React's state and refs to manage the visibility and position of the SVG element.

This hook is particularly useful in UI scenarios where a floating note, tooltip, or helper graphic needs to follow the mouse cursor smoothly, appearing or disappearing based on user interaction or application state.

Detailed Description of useMoveNote Hook

Function Signature

function useMoveNote(): {
  ref: React.RefObject<SVGSVGElement>;
  showImage: () => void;
  hideImage: () => void;
  mouse: { clientX: number; clientY: number; };
  imgVisible: boolean;
}

Purpose

• Tracks the mouse cursor position.

• Provides a reference to an SVG element that can be positioned near the mouse cursor.

• Controls visibility (show/hide) of the SVG element.

• Updates the SVG element's position dynamically on mouse movement.

Internal Logic and Implementation Details

1. Ref (ref)
   A React ref attached to an SVG element (SVGSVGElement). This ref is used to directly manipulate the SVG's CSS top and left properties to position it near the cursor.

2. Mouse Position (mouse)
   Obtained from the useMouse hook (from ahooks), which provides the current mouse coordinates (clientX, clientY) relative to the viewport.

3. Visibility State (imgVisible)
   A boolean state flag that controls whether the SVG element is visible or hidden.

4. Visibility Control Functions

   • toggleVisible(visible: boolean): Sets imgVisible to the given boolean.

   • showImage(): Calls toggleVisible(true) to show the SVG.

   • hideImage(): Calls toggleVisible(false) to hide the SVG.

5. Position Update Effect
   A useEffect hook watches changes in mouse coordinates (mouse.clientX, mouse.clientY). When the mouse moves:

   • The SVG element's style.top is set to mouse.clientY - 70 pixels.

   • The SVG element's style.left is set to mouse.clientX + 10 pixels.

   This offset positions the SVG slightly above and to the right of the cursor to avoid obstructing the pointer.

Returned Object

The hook returns an object containing:

Usage Example

import React from 'react';
import { useMoveNote } from './use-move-note';

export function MoveNoteExample() {
  const { ref, showImage, hideImage, imgVisible } = useMoveNote();

  return (
    <>
      <button
        onMouseEnter={showImage}
        onMouseLeave={hideImage}
      >
        Hover me
      </button>

      {imgVisible && (
        <svg
          ref={ref}
          style={{
            position: 'fixed',
            pointerEvents: 'none',
            transition: 'top 0.1s, left 0.1s',
            width: '100px',
            height: '50px',
            backgroundColor: 'rgba(0,0,0,0.7)',
            color: 'white',
          }}
        >
          <text x="10" y="20">Note follows cursor</text>
        </svg>
      )}
    </>
  );
}

In this example:

• When the user hovers over the button, the SVG note becomes visible and follows the mouse cursor.

• When the mouse leaves the button, the SVG note hides.

Interaction with Other Parts of the Application

• Dependency on ahooks: The hook depends on the useMouse hook from the ahooks library to track global mouse movements.

• Integration Point: The hook is designed to be integrated into components that need a floating SVG note or tooltip following the cursor.

• Ref Usage: The SVG element controlled by this hook must be rendered with the ref provided to enable positioning.

• Visibility Control: The consumer component controls the visibility triggers (e.g., mouse events) by invoking showImage and hideImage.

Important Implementation Notes

• The hook uses fixed pixel offsets (-70 for top and +10 for left) to position the note relative to the cursor. These values can be adjusted to suit different UI layouts or note sizes.

• The SVG element's style must include position: fixed (or absolute relative to a positioned ancestor) to ensure it moves correctly with the viewport.

• The pointerEvents: 'none' style is recommended on the SVG to prevent it from blocking mouse interactions.

• The hook does not handle the rendering of the SVG itself, only its positioning and visibility state management.

Mermaid Diagram: Flowchart of useMoveNote Hook

flowchart TD
    A[useMoveNote Hook] --> B[Initialize ref (SVGSVGElement)]
    A --> C[Track mouse position using useMouse]
    A --> D[State: imgVisible (boolean)]
    A --> E[Define toggleVisible(visible)]
    E --> F[showImage() calls toggleVisible(true)]
    E --> G[hideImage() calls toggleVisible(false)]
    C --> H[useEffect: on mouse movement]
    H --> I[Update ref.current.style.top and left]
    A --> J[Return { ref, showImage, hideImage, mouse, imgVisible }]

Summary

The useMoveNote hook is a streamlined utility for React applications to display and position an SVG note relative to the user's mouse cursor. It abstracts the management of mouse tracking, element positioning, and visibility toggling into a reusable hook, enhancing UI interactivity with minimal setup. It is designed for easy integration with components that require floating annotations, tooltips, or helper visuals that follow the cursor dynamically.