Rename useCursorLock useCssCursorLock + add docs

theatre/studio/src/panels/SequenceEditorPanel/DopeSheet/Right/BasicKeyframedTrack/KeyframeEditor/Dot.tsx

@@ -14,7 +14,7 @@ import styled from 'styled-components'
 import type KeyframeEditor from './KeyframeEditor'
 import {useLockFrameStampPosition} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
 import {attributeNameThatLocksFramestamp} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
-import {useCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
+import {useCssCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
 import SnapCursor from './SnapCursor.svg'
 import selectedKeyframeIdsIfInSingleTrack from '@theatre/studio/panels/SequenceEditorPanel/DopeSheet/Right/BasicKeyframedTrack/selectedKeyframeIdsIfInSingleTrack'
 
@@ -237,7 +237,7 @@ function useDragKeyframe(
 
   useDrag(node, gestureHandlers)
 
-  useCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
+  useCssCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
 
   return [isDragging]
 }

theatre/studio/src/panels/SequenceEditorPanel/DopeSheet/Right/HorizontallyScrollableArea.tsx

@@ -10,7 +10,7 @@ import React, {useLayoutEffect, useMemo} from 'react'
 import styled from 'styled-components'
 import {useReceiveVerticalWheelEvent} from '@theatre/studio/panels/SequenceEditorPanel/VerticalScrollContainer'
 import {pointerEventsAutoInNormalMode} from '@theatre/studio/css'
-import {useCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
+import {useCssCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
 import type {IRange} from '@theatre/shared/utils/types'
 
 const Container = styled.div`
@@ -148,7 +148,7 @@ function useDragHandlers(
 
   const [isDragging] = useDrag(containerEl, handlers)
 
-  useCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
+  useCssCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
 }
 
 function useHandlePanAndZoom(

theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/GraphEditorDotNonScalar.tsx

@@ -13,7 +13,7 @@ import type {Keyframe} from '@theatre/core/projects/store/types/SheetState_Histo
 import {useLockFrameStampPosition} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
 import {attributeNameThatLocksFramestamp} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
 import {pointerEventsAutoInNormalMode} from '@theatre/studio/css'
-import {useCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
+import {useCssCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
 
 export const dotSize = 6
 
@@ -170,7 +170,7 @@ function useDragKeyframe(
   }, [])
 
   useDrag(node, gestureHandlers)
-  useCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
+  useCssCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
   return isDragging
 }
 

theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/GraphEditorDotScalar.tsx

@@ -13,7 +13,7 @@ import type {Keyframe} from '@theatre/core/projects/store/types/SheetState_Histo
 import {useLockFrameStampPosition} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
 import {attributeNameThatLocksFramestamp} from '@theatre/studio/panels/SequenceEditorPanel/FrameStampPositionProvider'
 import {pointerEventsAutoInNormalMode} from '@theatre/studio/css'
-import {useCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
+import {useCssCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
 
 export const dotSize = 6
 
@@ -224,7 +224,7 @@ function useDragKeyframe(
   }, [])
 
   useDrag(node, gestureHandlers)
-  useCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'move')
+  useCssCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'move')
   return isDragging
 }
 

theatre/studio/src/panels/SequenceEditorPanel/RightOverlay/FocusRangeZone/FocusRangeThumb.tsx

@@ -7,7 +7,7 @@ import getStudio from '@theatre/studio/getStudio'
 import type {SequenceEditorPanelLayout} from '@theatre/studio/panels/SequenceEditorPanel/layout/layout'
 import {topStripHeight} from '@theatre/studio/panels/SequenceEditorPanel/RightOverlay/TopStrip'
 import type {CommitOrDiscard} from '@theatre/studio/StudioStore/StudioStore'
-import {useCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
+import {useCssCursorLock} from '@theatre/studio/uiComponents/PointerEventsHandler'
 import useDrag from '@theatre/studio/uiComponents/useDrag'
 import useRefAndState from '@theatre/studio/utils/useRefAndState'
 import React, {useMemo, useRef, useState} from 'react'
@@ -211,7 +211,7 @@ const FocusRangeThumb: React.FC<{
 
   useDrag(hitZoneNode, gestureHandlers)
 
-  useCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
+  useCssCursorLock(isDragging, 'draggingPositionInSequenceEditor', 'ew-resize')
 
   return usePrism(() => {
     const existingRange = existingRangeD.getValue()

theatre/studio/src/uiComponents/PointerEventsHandler.tsx

@@ -69,12 +69,22 @@ const PointerEventsHandler: React.FC<{
 }
 
 /**
- * Question: Is this referring to the user's pointer input device?
+ * A "locking" mechanism for managing style.cursor values.
- * Or is this locking related to the playhead "cursor"?
+ *
+ * Putting this behind a lock is important so we can properly manage
+ * multiple features all coordinating to style the cursor.
+ *
+ * This will also track a stack of different cursor styles so that
+ * adding a style to be the "foremost" cursor can override a previous style,
+ * but then "unlocking" that style will again reveal the existing styles.
+ *
+ * It behaves a bit like a stack.
  */
-export const useCursorLock = (
+export const useCssCursorLock = (
+  /** Whether to enable the provided cursor style */
   enabled: boolean,
   className: string,
+  /** e.g. `"ew"`, `"help"`, `"pointer"`, `"text"`, etc */
   cursor: string,
 ) => {
   const ctx = useContext(context)

theatre/studio/src/uiComponents/useDrag.ts

@@ -1,7 +1,7 @@
 import type {$FixMe} from '@theatre/shared/utils/types'
 import {useLayoutEffect, useRef} from 'react'
 import useRefAndState from '@theatre/studio/utils/useRefAndState'
-import {useCursorLock} from './PointerEventsHandler'
+import {useCssCursorLock} from './PointerEventsHandler'
 
 export type UseDragOpts = {
   /**
@@ -52,7 +52,7 @@ export default function useDrag(
     'dragStartCalled' | 'dragging' | 'notDragging'
   >('notDragging')
 
-  useCursorLock(
+  useCssCursorLock(
     mode === 'dragging' && typeof opts.lockCursorTo === 'string',
     'dragging',
     opts.lockCursorTo!,