@tremolo-ui/react 0.5.0 → 0.6.0

package/src/components/PointsEditor/Container.tsx

@@ -1,36 +1,96 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react'
+import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
 
-import { useComposedRefs } from '../_util/composeRefs'
+import { useComposedRefs } from '../../compose-refs'
+import { useDragValue } from '../../hooks/useDragValue'
+import { useWheel } from '../../hooks/useWheel'
+import { Placement } from '../_util/Placement'
 
 import { usePointsEditorContext } from './context'
+import { AXIS } from './Point'
 
 export interface PointsEditorContainerProps {
   /** `<PointsEditor.Point />` goes here. */
   children?: ReactNode
-  ref?: Ref<HTMLDivElement>
 }
 
-export function Container({
-  children,
-  className,
-  ref,
-  ...props
-}: PointsEditorContainerProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorContainerProps>) {
-  const containerRef = usePointsEditorContext((s) => s.containerRef)
-
-  // The container is what the pointer position is normalized against, so the
-  // context ref is composed with any ref the caller passed.
-  const composedRef = useComposedRefs<HTMLDivElement>(ref, containerRef)
-
-  return (
-    <div
-      ref={composedRef}
-      className={clsx('tremolo-points-editor-container', className)}
-      {...props}
-    >
-      {children}
-    </div>
-  )
-}
+type Props = PointsEditorContainerProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorContainerProps>
+
+export const Container = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
+  function Container({ children, className, style, ...props }, forwardedRef) {
+    const {
+      containerRef,
+      disabled,
+      selectable,
+      isPointElement,
+      nudgeFocusedPoint,
+      beginSelectionBox,
+      moveSelectionBox,
+      endSelectionBox,
+    } = usePointsEditorContext()
+    const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
+      axis: AXIS,
+      baseElementRef: containerRef,
+      // A press that landed on a point belongs to that point. Declining here
+      // rather than in onDragStart matters: by then the container would already
+      // have taken the pointer capture away from the point.
+      shouldStart: (event) =>
+        !disabled && !isPointElement(event.target as Element | null),
+      onDragStart: ([x, y], state) => {
+        beginSelectionBox({ x, y }, state.event)
+      },
+      onChange: ([x, y]) => moveSelectionBox({ x, y }),
+      onDragEnd: endSelectionBox,
+    })
+
+    // One listener for the whole editor rather than one per point: a wheel
+    // event only reaches what the cursor is over, and a point is a 16px
+    // target, so the focused point takes it from anywhere over the editor —
+    // the way it does for Slider and XYPad.
+    useWheel(
+      (event) => {
+        // Scrolling up moves the point towards y = 0; shift switches to x.
+        // Browsers turn shift+wheel into horizontal scrolling: `deltaY` comes
+        // out empty and `deltaX` carries the movement. Reading whichever axis
+        // moved keeps shift working as the x-axis modifier — and picks up a
+        // trackpad's own horizontal gesture, which never had a modifier.
+        const horizontal = event.deltaX !== 0
+        const delta = horizontal ? event.deltaX : event.deltaY
+        if (delta === 0) return
+        const axis = horizontal || event.shiftKey ? 'x' : 'y'
+        const direction = delta < 0 ? -1 : 1
+        if (nudgeFocusedPoint(axis, direction, event)) event.preventDefault()
+      },
+      { target: containerRef },
+    )
+
+    // The container is what the pointer position is normalized against, so the
+    // context ref is composed with any ref the caller passed.
+    // Only attached when there is a selection to draw: `createDrag` puts
+    // `touch-action: none` on whatever it holds, and an editor that cannot
+    // select has no reason to stop the page scrolling under a finger.
+    const composedRef = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
+      containerRef,
+      selectable && !disabled ? dragRefCallback : undefined,
+    )
+
+    return (
+      <div
+        ref={composedRef}
+        className={className}
+        style={{
+          // The points inside are placed against this box, over the
+          // background and under the selection box.
+          position: 'absolute',
+          inset: 0,
+          zIndex: 10,
+          ...style,
+        }}
+        {...props}
+      >
+        <Placement name="PointsEditor.Container">{children}</Placement>
+      </div>
+    )
+  },
+)

package/src/components/PointsEditor/Point.tsx

@@ -1,14 +1,30 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, useCallback, useState } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
 
-import { applyDelta, clamp, InputEventOption } from '@tremolo-ui/functions'
+import {
+  applyDelta,
+  clamp,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  selectModifier,
+} from '@tremolo-ui/functions'
 
+import { useComposedRefs } from '../../compose-refs'
 import { useDragValue } from '../../hooks/useDragValue'
-import { useWheel } from '../../hooks/useWheel'
-import { addUserSelectNone, removeUserSelectNone } from '../_util'
-import { useComposedRefs } from '../_util/composeRefs'
+import { cssLength } from '../_util/css-length'
+import { useCheckPlacement } from '../_util/Placement'
+import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-import { usePointsEditorContext } from './context'
+import { type PointRegistration, usePointsEditorContext } from './context'
 
 export type PointBaseType = { x: number; y: number }
 
@@ -23,14 +39,32 @@ export function clampPoint(
   return { x: newX, y: newY }
 }
 
-export interface PointProps<T extends PointBaseType> {
+export interface PointsEditorPointProps<T extends PointBaseType> {
+  /**
+   * Where the point is, as `{ x, y }` from 0 to 1 on each axis, with `y`
+   * growing downwards.
+   */
   value: T
+  /** Drawn inside the point: the theme's own dot stands when it is left out. */
+  children?: ReactNode
+  /**
+   * How the selection refers to this point. One is generated when it is left
+   * out, which lasts as long as the point is mounted — give your own if the
+   * selection has to survive a remount, or be recognised in your own state.
+   */
+  id?: string
+  /** The lowest position the point can take, per axis. An axis left out is 0. */
   min?: Partial<PointBaseType>
+  /** The highest position the point can take, per axis. An axis left out is 1. */
   max?: Partial<PointBaseType>
 
+  /** 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`. */
@@ -39,12 +73,26 @@ export interface PointProps<T extends PointBaseType> {
   readonly?: boolean
 
   /** Overrides the `wheel` of `PointsEditor.Root`. */
-  wheel?: InputEventOption | null
+  wheel?: ModifierValue<InputEventOption> | null
   /** Overrides the `keyboard` of `PointsEditor.Root`. */
-  keyboard?: InputEventOption | null
+  keyboard?: ModifierValue<InputEventOption> | null
 
+  /**
+   * The accessible name of each axis. There are two range inputs inside the
+   * point, so this takes one name per axis; a single string names them both.
+   */
+  'aria-label'?: string | Partial<Record<'x' | 'y', string>>
+  /** What the value of each axis means, when the number does not say it. */
+  'aria-valuetext'?: string | Partial<Record<'x' | 'y', string>>
+
+  /**
+   * 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
 }
 
@@ -52,21 +100,36 @@ export interface PointProps<T extends PointBaseType> {
  * 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.
  */
-const AXIS = { min: 0, max: 1 }
+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.
+ */
+function perAxis(
+  value: string | Partial<Record<'x' | 'y', string>> | undefined,
+  axis: 'x' | 'y',
+) {
+  return typeof value === 'string' ? value : value?.[axis]
+}
 
 export function Point<T extends PointBaseType>({
   value,
+  children,
+  id: idProp,
   min,
   max,
   size,
-  width = 16,
-  height = 16,
+  width,
+  height,
   color,
 
   disabled: _disabled,
   readonly: _readonly,
   wheel: _wheel,
   keyboard: _keyboard,
+  'aria-label': ariaLabel,
+  'aria-valuetext': ariaValuetext,
 
   onChange,
   onDragStart,
@@ -76,8 +139,10 @@ export function Point<T extends PointBaseType>({
   style,
   onPointerDown,
   onKeyDown,
+  onFocus,
   ...props
-}: PointProps<T> & Omit<ComponentPropsWithoutRef<'div'>, keyof PointProps<T>>) {
+}: PointsEditorPointProps<T> &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>) {
   const {
     containerRef,
     externalStyles,
@@ -85,69 +150,114 @@ export function Point<T extends PointBaseType>({
     readonly: rootReadonly,
     wheel: rootWheel,
     keyboard: rootKeyboard,
+    dragSensitivity,
+    selection,
+    registerPoint,
+    beginPointDrag,
+    movePointDrag,
+    nudgeSelection,
   } = usePointsEditorContext()
 
+  const generatedId = useId()
+  const id = idProp ?? generatedId
+  const selected = selection.includes(id)
+
   const disabled = _disabled ?? rootDisabled
   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
   const keyboard = _keyboard === undefined ? rootKeyboard : _keyboard
 
+  useCheckPlacement('PointsEditor.Point', 'PointsEditor.Container')
+
   // Compared against the focus below, so the point needs its own element.
   const [element, setElement] = useState<HTMLDivElement | null>(null)
+  const xInputRef = useRef<HTMLInputElement>(null)
+  const yInputRef = useRef<HTMLInputElement>(null)
+
+  // 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>({
+    value,
+    min,
+    max,
+    readonly: inactive,
+    onChange,
+    element,
+    wheel,
+  })
+  useEffect(() => {
+    registration.current = {
+      value,
+      min,
+      max,
+      readonly: inactive,
+      onChange,
+      element,
+      wheel,
+    }
+  })
+
+  useEffect(() => registerPoint(id, registration), [id, registerPoint])
+
+  /** Where the pointer was when the drag started, to measure the move from. */
+  const pointerOrigin = useRef<PointBaseType | null>(null)
 
   // The value is the position itself: no scaling, and no rounding to a step.
   const { refCallback: dragRefCallback, dragging } =
     useDragValue<HTMLDivElement>({
       axis: AXIS,
       baseElementRef: containerRef,
-      cursor: readonly ? undefined : externalStyles.cursor,
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      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
+      // same amount.
       onChange: ([x, y]) => {
-        if (readonly) return
-
-        onChange?.(clampPoint({ x, y }, min, max))
+        const origin = pointerOrigin.current
+        if (!origin) return
+        movePointDrag({ x: x - origin.x, y: y - origin.y })
       },
-      onDragStart: ([x, y]) => {
-        if (readonly) return
-        if (externalStyles.userSelectNone) addUserSelectNone()
+      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)
+        pointerOrigin.current = { x, y }
+        xInputRef.current?.focus()
 
-        onDragStart?.(clampPoint({ x, y }, min, max))
+        if (inactive) return
+        onDragStart?.(clampPoint(value, min, max))
       },
-      onDragEnd: ([x, y]) => {
-        if (readonly) return
-        if (externalStyles.userSelectNone) removeUserSelectNone()
+      onDragEnd: () => {
+        pointerOrigin.current = null
 
-        onDragEnd?.(clampPoint({ x, y }, min, max))
+        if (inactive) return
+        onDragEnd?.(clampPoint(value, min, max))
       },
     })
 
   const nudge = useCallback(
-    (axis: 'x' | 'y', direction: number, option: InputEventOption) => {
-      const next = applyDelta(value[axis], direction, option, AXIS)
-      onChange?.(clampPoint({ ...value, [axis]: next }, min, max))
-    },
-    [value, min, max, onChange],
-  )
-
-  // The listener sits on the container rather than on the point: a wheel event
-  // only reaches what the cursor is over, and a point is a 16px target. Every
-  // point sees the event and the focused one acts, so the wheel works anywhere
-  // over the editor, the way it does for Slider and XYPad.
-  //
-  // The focus test is an identity check, not `contains`: with `contains` every
-  // point would match the container's focus and they would all move at once.
-  useWheel(
-    (event) => {
-      if (!onChange || readonly || !wheel) return
-      if (!element || element.ownerDocument.activeElement !== element) return
-      event.preventDefault()
-      // Scrolling up moves the point towards y = 0; shift switches to x.
-      const axis = event.shiftKey ? 'x' : 'y'
-      const direction = event.deltaY < 0 ? -1 : 1
-      nudge(axis, direction, wheel)
+    (
+      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,
+      })
     },
-    { target: containerRef },
+    [value, id, nudgeSelection],
   )
 
   const refCallback = useComposedRefs<HTMLDivElement>(
@@ -156,47 +266,97 @@ export function Point<T extends PointBaseType>({
   )
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
-    if (!onChange || readonly || !keyboard) return
     const key = event.key
-    if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
-      event.preventDefault()
-      // y grows downwards, so ArrowUp moves the point towards 0.
-      const axis = key === 'ArrowRight' || key === 'ArrowLeft' ? 'x' : 'y'
-      const direction = key === 'ArrowLeft' || key === 'ArrowUp' ? -1 : 1
-      nudge(axis, direction, keyboard)
-    }
+    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'
+    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)
   }
 
-  const colors: Record<string, string | undefined> = {
-    '--color': color,
-  }
+  const current = clampPoint(value, min, max)
 
   return (
-    // The point is a drag handle rather than a control of a known kind: it has
-    // no single value to announce, so there is no role that fits it.
-    // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+    // The visual point has two values, so its semantics live on the two range
+    // inputs nested inside it rather than on this drag handle.
+    // oxlint-disable-next-line jsx-a11y/no-static-element-interactions
     <div
       ref={refCallback}
-      className={clsx('tremolo-points-editor-point', className)}
-      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
-      tabIndex={0}
-      aria-disabled={disabled}
-      aria-readonly={readonly}
-      data-dragging={dragging}
-      style={{
-        ...colors,
-        width: size ?? width,
-        height: size ?? height,
-        left: `${value.x * 100}%`,
-        top: `${value.y * 100}%`,
-        ...style,
-      }}
+      className={className}
+      data-disabled={disabled ? '' : 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
+      // it is passed on to the input below.
+      tabIndex={-1}
+      data-dragging={dragging ? '' : undefined}
+      data-selected={selected ? '' : undefined}
+      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',
+          translate: 'var(--translate, -50% -50%)',
+          ...style,
+          // Where the point is: the value, not a style.
+          left: `${value.x * 100}%`,
+          top: `${value.y * 100}%`,
+        } as CSSProperties
+      }
       onPointerDown={onPointerDown}
+      onFocus={(event) => {
+        // The point itself is not the control: its semantics live on the
+        // inputs, so whatever reaches it is handed to the first of them.
+        if (!disabled && event.target === event.currentTarget) {
+          xInputRef.current?.focus()
+        }
+        onFocus?.(event)
+      }}
       onKeyDown={(event) => {
         handleKeyDown(event)
         onKeyDown?.(event)
       }}
       {...props}
-    />
+    >
+      {(['x', 'y'] as const).map((axis) => (
+        <VisuallyHiddenRangeInput
+          key={axis}
+          ref={axis === 'x' ? xInputRef : yInputRef}
+          data-axis={axis}
+          value={current[axis]}
+          min={min?.[axis] ?? 0}
+          max={max?.[axis] ?? 1}
+          step="any"
+          disabled={disabled}
+          aria-readonly={readonly}
+          aria-orientation={axis === 'x' ? 'horizontal' : 'vertical'}
+          aria-label={perAxis(ariaLabel, axis) ?? axis}
+          aria-valuetext={perAxis(ariaValuetext, axis)}
+          onChange={(event) => {
+            if (readonly) {
+              event.currentTarget.value = String(current[axis])
+              return
+            }
+            const delta = event.currentTarget.valueAsNumber - value[axis]
+            nudgeSelection(id, {
+              x: axis === 'x' ? delta : 0,
+              y: axis === 'y' ? delta : 0,
+            })
+          }}
+        />
+      ))}
+      {children}
+    </div>
   )
 }

package/src/components/PointsEditor/SelectionBox.tsx

@@ -0,0 +1,54 @@
+import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
+
+import { useCheckPlacement } from '../_util/Placement'
+
+import { usePointsEditorContext } from './context'
+
+export interface PointsEditorSelectionBoxProps {
+  /** Drawn inside the box, which is only there while a drag is running. */
+  children?: ReactNode
+}
+
+/**
+ * The box a drag on empty space draws, and what it covers is selected.
+ *
+ * Nothing is rendered while no drag is running, and leaving it out leaves the
+ * editor without one — the selection still works, it just cannot be seen.
+ */
+export function SelectionBox({
+  children,
+  className,
+  style,
+  ...props
+}: PointsEditorSelectionBoxProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorSelectionBoxProps>) {
+  useCheckPlacement('PointsEditor.SelectionBox', 'PointsEditor.Container')
+
+  const selectionBox = usePointsEditorContext((s) => s.selectionBox)
+  if (!selectionBox) return null
+
+  return (
+    <div
+      className={className}
+      {...props}
+      style={
+        {
+          // Drawn over the points while a drag runs, and taking none of the
+          // pointer: the drag underneath is what it is reporting on.
+          position: 'absolute',
+          zIndex: 20,
+          pointerEvents: 'none',
+          ...style,
+          // Where the box is and how big it is: the drag, not a style, so it
+          // is written after whatever the caller passed.
+          left: `${selectionBox.x * 100}%`,
+          top: `${selectionBox.y * 100}%`,
+          width: `${selectionBox.width * 100}%`,
+          height: `${selectionBox.height * 100}%`,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  )
+}