@tremolo-ui/react 0.7.0 → 0.9.0

package/src/components/PointsEditor/Point.tsx

@@ -1,7 +1,6 @@
 import {
   ComponentPropsWithoutRef,
   CSSProperties,
-  useCallback,
   useEffect,
   useId,
   useRef,
@@ -9,38 +8,30 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
+  type ChangeSource,
   type InputEventOption,
-  type ModifierState,
   type ModifierValue,
-  selectModifier,
+  type PointPosition,
+  type PointsEditorPoint,
 } from '@tremolo-ui/dom'
-import { clamp } from '@tremolo-ui/functions'
+import {
+  arrowKeyMove,
+  clampPoint,
+  POINT_AXIS,
+  selectModifier,
+} from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
+import { useChangeGesture } from '../../hooks/_internal/useChangeGesture'
 import { useDragValue } from '../../hooks/useDragValue'
-import { cssLength } from '../_util/css-length'
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-import { type PointRegistration, usePointsEditorContext } from './context'
+import { usePointsEditorContext } from './context'
 
 import type { CSSVariables } from '../../css-variables'
 
-export type PointBaseType = { x: number; y: number }
-
-export function clampPoint(
-  point: PointBaseType,
-  min?: Partial<PointBaseType>,
-  max?: Partial<PointBaseType>,
-) {
-  const { x, y } = point
-  const newX = clamp(x, min?.x ?? 0, max?.x ?? 1)
-  const newY = clamp(y, min?.y ?? 0, max?.y ?? 1)
-  return { x: newX, y: newY }
-}
-
-export interface PointsEditorPointProps<T extends PointBaseType> {
+export interface PointsEditorPointProps<T extends PointPosition> {
   /**
    * Where the point is, as `{ x, y }` from 0 to 1 on each axis, with `y`
    * growing downwards.
@@ -53,23 +44,17 @@ export interface PointsEditorPointProps<T extends PointBaseType> {
    */
   id?: string
   /** The lowest position the point can take, per axis. An axis left out is 0. */
-  min?: Partial<PointBaseType>
+  min?: Partial<PointPosition>
   /** The highest position the point can take, per axis. An axis left out is 1. */
-  max?: Partial<PointBaseType>
+  max?: Partial<PointPosition>
 
-  /** Width and height at once. Sets both `--width` and `--height`. */
-  size?: number | string
-  /** Sets `--width`; the size the theme gives it stands when omitted. */
-  width?: number | string
-  /** Sets `--height`; the size the theme gives it stands when omitted. */
-  height?: number | string
   /** Sets `--color`, for the theme to colour the point with. */
   color?: string
 
   /** Overrides the `disabled` of `PointsEditor.Root`. */
   disabled?: boolean
-  /** Overrides the `readonly` of `PointsEditor.Root`. */
-  readonly?: boolean
+  /** Overrides the `readOnly` of `PointsEditor.Root`. */
+  readOnly?: boolean
 
   /** Overrides the `wheel` of `PointsEditor.Root`. */
   wheel?: ModifierValue<InputEventOption> | null
@@ -88,22 +73,30 @@ export interface PointsEditorPointProps<T extends PointBaseType> {
    * Called with the new position when the point is dragged or moved by the
    * arrow keys or the wheel, including when it moves along with a selection.
    */
-  onChange?: (value: PointBaseType) => void
-  /** Called when a drag on this point starts, with where the point is. */
-  onDragStart?: (value: PointBaseType) => void
-  /** Called when that drag ends, with where the point is. */
-  onDragEnd?: (value: PointBaseType) => void
+  onChange?: (value: PointPosition) => void
+  /**
+   * Called when a change of this point starts — a drag on it, the first wheel
+   * notch or arrow key while it has the focus — with where it is and what the
+   * change is made with. The points that move along with a selection report
+   * through `onChange` only: the change belongs to the point being operated.
+   */
+  onChangeStart?: (value: PointPosition, source: ChangeSource) => void
+  /**
+   * Called when that change ends, with where the point is: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: PointPosition, source: ChangeSource) => void
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number
 
-  style?: CSSProperties &
-    CSSVariables<'width' | 'height' | 'color' | 'translate'>
+  style?: CSSProperties & CSSVariables<'color' | 'translate'>
 }
 
-/**
- * A point is placed by its position within the container, so its value is a
- * position: 0..1 on each axis, with y growing downwards.
- */
-export const AXIS = { min: 0, max: 1 }
-
 /**
  * One setting for both axes, or one per axis. The point holds a range input
  * for each, so anything that names or describes it comes in a pair.
@@ -115,27 +108,25 @@ function perAxis(
   return typeof value === 'string' ? value : value?.[axis]
 }
 
-export function Point<T extends PointBaseType>({
+export function Point<T extends PointPosition>({
   value,
   children,
   id: idProp,
   min,
   max,
-  size,
-  width,
-  height,
   color,
 
   disabled: _disabled,
-  readonly: _readonly,
+  readOnly: _readOnly,
   wheel: _wheel,
   keyboard: _keyboard,
   'aria-label': ariaLabel,
   'aria-valuetext': ariaValuetext,
 
   onChange,
-  onDragStart,
-  onDragEnd,
+  onChangeStart,
+  onChangeEnd,
+  changeEndDelay,
 
   className,
   style,
@@ -147,17 +138,14 @@ export function Point<T extends PointBaseType>({
   Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>) {
   const {
     containerRef,
-    externalStyles,
+    dragCursor,
     disabled: rootDisabled,
-    readonly: rootReadonly,
+    readOnly: rootReadOnly,
     wheel: rootWheel,
     keyboard: rootKeyboard,
     dragSensitivity,
     selection,
-    registerPoint,
-    beginPointDrag,
-    movePointDrag,
-    nudgeSelection,
+    editor,
   } = usePointsEditorContext()
 
   const generatedId = useId()
@@ -165,8 +153,8 @@ export function Point<T extends PointBaseType>({
   const selected = selection.includes(id)
 
   const disabled = _disabled ?? rootDisabled
-  const readonly = _readonly ?? rootReadonly
-  const inactive = disabled || readonly
+  const readOnly = _readOnly ?? rootReadOnly
+  const inactive = disabled || readOnly
   // `null` means "no event" and has to survive the fallback, so `??` is not
   // enough: only an omitted prop inherits from the root.
   const wheel = _wheel === undefined ? rootWheel : _wheel
@@ -174,6 +162,19 @@ export function Point<T extends PointBaseType>({
 
   useCheckPlacement('PointsEditor.Point', 'PointsEditor.Container')
 
+  const current = clampPoint(value, min, max)
+  const gesture = useChangeGesture(
+    current,
+    { onChangeStart, onChangeEnd, changeEndDelay },
+    inactive,
+  )
+  // Every move reaches the point through here, whatever moved it, so the
+  // last one is what `onChangeEnd` gives.
+  const handleChange = (next: PointPosition) => {
+    gesture.changed(next)
+    onChange?.(next)
+  }
+
   // Compared against the focus below, so the point needs its own element.
   const [element, setElement] = useState<HTMLDivElement | null>(null)
   const xInputRef = useRef<HTMLInputElement>(null)
@@ -182,14 +183,15 @@ export function Point<T extends PointBaseType>({
   // What the editor needs to move this point along with the rest of a
   // selection. Rewritten after every render rather than kept in the registry
   // itself: the value changes on every frame of a drag.
-  const registration = useRef<PointRegistration>({
+  const registration = useRef<PointsEditorPoint>({
     value,
     min,
     max,
     readonly: inactive,
-    onChange,
+    onChange: onChange ? handleChange : undefined,
     element,
     wheel,
+    beforeWheel: () => gesture.pulse('wheel'),
   })
   useEffect(() => {
     registration.current = {
@@ -197,25 +199,29 @@ export function Point<T extends PointBaseType>({
       min,
       max,
       readonly: inactive,
-      onChange,
+      onChange: onChange ? handleChange : undefined,
       element,
       wheel,
+      beforeWheel: () => gesture.pulse('wheel'),
     }
   })
 
-  useEffect(() => registerPoint(id, registration), [id, registerPoint])
+  useEffect(
+    () => editor.registerPoint(id, () => registration.current),
+    [id, editor],
+  )
 
   /** Where the pointer was when the drag started, to measure the move from. */
-  const pointerOrigin = useRef<PointBaseType | null>(null)
+  const pointerOrigin = useRef<PointPosition | null>(null)
 
   // The value is the position itself: no scaling, and no rounding to a step.
   const { refCallback: dragRefCallback, dragging } =
     useDragValue<HTMLDivElement>({
-      axis: AXIS,
+      axis: POINT_AXIS,
       baseElementRef: containerRef,
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       shouldStart: () => !disabled,
       // The value is a move rather than a position: the point keeps the offset
       // it was grabbed at, and everything else selected moves with it by the
@@ -223,68 +229,48 @@ export function Point<T extends PointBaseType>({
       onChange: ([x, y]) => {
         const origin = pointerOrigin.current
         if (!origin) return
-        movePointDrag({ x: x - origin.x, y: y - origin.y })
+        editor.movePointDrag({ x: x - origin.x, y: y - origin.y })
       },
       onDragStart: ([x, y], state) => {
         // The press decides the selection before the snapshot is taken, so it
         // happens here rather than in an onPointerDown: a native listener on
         // the element runs before React's, and the two would disagree.
-        beginPointDrag(id, state.event)
+        editor.beginPointDrag(id, state.event)
         pointerOrigin.current = { x, y }
         xInputRef.current?.focus()
 
-        if (inactive) return
-        onDragStart?.(clampPoint(value, min, max))
+        if (!inactive) gesture.hold('pointer')
       },
       onDragEnd: () => {
         pointerOrigin.current = null
-
-        if (inactive) return
-        onDragEnd?.(clampPoint(value, min, max))
+        gesture.end()
       },
     })
 
-  const nudge = useCallback(
-    (
-      axis: 'x' | 'y',
-      direction: number,
-      option: ModifierValue<InputEventOption>,
-      modifiers: ModifierState,
-    ) => {
-      const next = applyDelta(value[axis], direction, option, AXIS, modifiers)
-      // As a move, so that the rest of the selection comes along and the whole
-      // group stops together at the edge.
-      nudgeSelection(id, {
-        x: axis === 'x' ? next - value.x : 0,
-        y: axis === 'y' ? next - value.y : 0,
-      })
-    },
-    [value, id, nudgeSelection],
-  )
-
   const refCallback = useComposedRefs<HTMLDivElement>(
     dragRefCallback,
     setElement,
   )
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
-    const key = event.key
-    if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
-      return
-    // The key picks the axis, whichever of the two inputs holds the focus: a
-    // point is one control to the person moving it, and the focus lands on the
-    // x input, so reading the axis off the input would leave the y axis with
-    // no keys at all.
-    const axis = key === 'ArrowRight' || key === 'ArrowLeft' ? 'x' : 'y'
+    // The key picks the axis, whichever of the two inputs holds the focus:
+    // the focus lands on the x input, so reading the axis off the input would
+    // leave the y axis with no keys at all. y grows downwards, so ArrowUp
+    // moves the point towards 0.
+    const move = arrowKeyMove(event.key)
+    if (!move) return
     event.preventDefault()
     if (!onChange || inactive || !keyboard) return
-    // y grows downwards, so ArrowUp moves the point towards 0.
-    const direction = key === 'ArrowLeft' || key === 'ArrowUp' ? -1 : 1
-    nudge(axis, direction, keyboard, event)
+    gesture.pulse('keyboard')
+    editor.nudgePoint(
+      id,
+      move.axis === 0 ? 'x' : 'y',
+      move.direction,
+      keyboard,
+      event,
+    )
   }
 
-  const current = clampPoint(value, min, max)
-
   return (
     // The visual point has two values, so its semantics live on the two range
     // inputs nested inside it rather than on this drag handle.
@@ -293,7 +279,7 @@ export function Point<T extends PointBaseType>({
       ref={refCallback}
       className={className}
       data-disabled={disabled ? '' : undefined}
-      data-readonly={readonly ? '' : undefined}
+      data-readonly={readOnly ? '' : undefined}
       // A press lands on the point, which cannot hold focus, and the browser
       // answers that by clearing the focus to the body — undoing the focus the
       // drag just gave the input. Taking the focus here keeps it inside, and
@@ -304,8 +290,6 @@ export function Point<T extends PointBaseType>({
       style={
         {
           '--color': color,
-          '--width': cssLength(size ?? width),
-          '--height': cssLength(size ?? height),
           // The mechanics of the position below: a point is placed by its
           // position in the container, measured from its own centre.
           position: 'absolute',
@@ -341,17 +325,17 @@ export function Point<T extends PointBaseType>({
           max={max?.[axis] ?? 1}
           step="any"
           disabled={disabled}
-          aria-readonly={readonly}
+          aria-readonly={readOnly}
           aria-orientation={axis === 'x' ? 'horizontal' : 'vertical'}
           aria-label={perAxis(ariaLabel, axis) ?? axis}
           aria-valuetext={perAxis(ariaValuetext, axis)}
           onChange={(event) => {
-            if (readonly) {
+            if (readOnly) {
               event.currentTarget.value = String(current[axis])
               return
             }
             const delta = event.currentTarget.valueAsNumber - value[axis]
-            nudgeSelection(id, {
+            editor.nudgeSelection(id, {
               x: axis === 'x' ? delta : 0,
               y: axis === 'y' ? delta : 0,
             })

package/src/components/PointsEditor/context.tsx

@@ -2,91 +2,39 @@ import { createContext, CSSProperties, RefObject, useContext } from 'react'
 
 import {
   type InputEventOption,
-  type ModifierState,
   type ModifierValue,
+  type PointsEditorInstance,
   type SelectionBoxRect,
 } from '@tremolo-ui/dom'
 
-import type { PointBaseType } from './Point'
-
-/**
- * What a `Point` tells the editor about itself, so that a selection can be
- * moved without the editor knowing how the points are stored.
- *
- * Held behind a ref and rewritten on every render: the value changes on every
- * frame of a drag, and a registry keyed on it would be rebuilt just as often.
- */
-export interface PointRegistration {
-  value: PointBaseType
-  min?: Partial<PointBaseType>
-  max?: Partial<PointBaseType>
-  readonly: boolean
-  onChange?: (value: PointBaseType) => void
-  /** The point's own element, to match the focus against. */
-  element: HTMLElement | null
-  /** The wheel option this point resolved, root inheritance applied. */
-  wheel: ModifierValue<InputEventOption> | null
-}
-
 export type PointsEditorContextValue = {
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   /** Inherited by every `Point`; `null` turns the wheel off. */
   wheel: ModifierValue<InputEventOption> | null
   /** Inherited by every `Point`; `null` turns the keyboard off. */
   keyboard: ModifierValue<InputEventOption> | null
   /** Inherited by every `Point`. See `PointsEditorProps.dragSensitivity`. */
   dragSensitivity: ModifierValue<number>
-  externalStyles: {
-    cursor?: CSSProperties['cursor']
-  }
-
+  /** Inherited by every `Point`. See `PointsEditorProps.dragCursor`. */
+  dragCursor: CSSProperties['cursor']
   /**
    * `Container` registers its element here; `Point` normalizes the pointer
    * against it, so a point is placed by its position within the container.
    */
   containerRef: RefObject<HTMLDivElement | null>
-
   /** Whether points can be selected at all. See `PointsEditorProps.selectable`. */
   selectable: boolean
   /** Ids of the points currently selected. Always empty while `selectable` is off. */
   selection: readonly string[]
-  /** Register a point so that a selection can move it with the rest. */
-  registerPoint: (id: string, entry: RefObject<PointRegistration>) => () => void
   /**
-   * Whether the element is a point, or inside one. The registry knows which
-   * elements the points are, so nothing has to be recognised by a class name.
+   * The selection and the moves, from `createPointsEditor` in
+   * `@tremolo-ui/dom`: every `Point` registers with it, and a press, a drag,
+   * a key or the wheel goes through it so that a selection moves as one.
    */
-  isPointElement: (element: Element | null | undefined) => boolean
-  /**
-   * A pointer went down on a point: works out the new selection and takes the
-   * snapshot the move will be measured against.
-   */
-  beginPointDrag: (id: string, modifiers: ModifierState) => void
-  /** Move everything the drag picked up, by one amount, clamped as one. */
-  movePointDrag: (delta: PointBaseType) => void
-  /**
-   * Move the selection by an amount that did not come from a drag — an arrow
-   * key or a wheel notch. The current values are the starting point.
-   */
-  nudgeSelection: (id: string, delta: PointBaseType) => void
-  /**
-   * Move the point that currently holds focus by one notch. The wheel listener
-   * belongs to `Container` rather than to every `Point`, so the lookup of who
-   * has focus happens here, where the registry is. Returns whether a point
-   * took it, so the caller knows whether to consume the event.
-   */
-  nudgeFocusedPoint: (
-    axis: 'x' | 'y',
-    direction: number,
-    modifiers: ModifierState,
-  ) => boolean
-
+  editor: PointsEditorInstance
   /** The selection box, while one is being dragged. */
   selectionBox: SelectionBoxRect | null
-  beginSelectionBox: (at: PointBaseType, modifiers: ModifierState) => void
-  moveSelectionBox: (to: PointBaseType) => void
-  endSelectionBox: () => void
 }
 
 const PointsEditorContext =