@tremolo-ui/react 0.5.0 → 0.7.0

package/src/components/PointsEditor/context.tsx

@@ -1,19 +1,44 @@
-import { createContext, RefObject, useContext } from 'react'
+import { createContext, CSSProperties, RefObject, useContext } from 'react'
 
-import type { InputEventOption } from '@tremolo-ui/functions'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  type SelectionBoxRect,
+} from '@tremolo-ui/dom'
 
-import { Cursor } from '../_util'
+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
   /** Inherited by every `Point`; `null` turns the wheel off. */
-  wheel: InputEventOption | null
+  wheel: ModifierValue<InputEventOption> | null
   /** Inherited by every `Point`; `null` turns the keyboard off. */
-  keyboard: InputEventOption | null
+  keyboard: ModifierValue<InputEventOption> | null
+  /** Inherited by every `Point`. See `PointsEditorProps.dragSensitivity`. */
+  dragSensitivity: ModifierValue<number>
   externalStyles: {
-    userSelectNone?: boolean
-    cursor?: Cursor
+    cursor?: CSSProperties['cursor']
   }
 
   /**
@@ -21,15 +46,58 @@ export type PointsEditorContextValue = {
    * 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.
+   */
+  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
+
+  /** 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 = createContext<PointsEditorContextValue | null>(null)
+const PointsEditorContext =
+  /* @__PURE__ */ createContext<PointsEditorContextValue | null>(null)
 
 export const PointsEditorProvider = PointsEditorContext.Provider
 
 /**
- * The settings `Root` was given, for the subcomponents to read. There is no
- * state to keep in sync: a point's value belongs to the `Point` that draws it.
+ * The settings `Root` was given, for the subcomponents to read. A point's
+ * value still belongs to the `Point` that draws it; what the root keeps is
+ * which points are selected, and a registry of who they are.
  */
 export function usePointsEditorContext(): PointsEditorContextValue
 export function usePointsEditorContext<T>(

package/src/components/PointsEditor/index.tsx

@@ -1,26 +1,75 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
+  RefObject,
+  useCallback,
+  useEffect,
   useMemo,
   useRef,
+  useState,
 } from 'react'
 
-import { InputEventOption } from '@tremolo-ui/functions'
+import {
+  applyDelta,
+  createSelectionBox,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  type SelectionBoxInstance,
+  type SelectionBoxRect,
+  type XY,
+} from '@tremolo-ui/dom'
+import { clamp, toPrecision } from '@tremolo-ui/functions'
 
-import { Cursor } from '../_util'
+import { DEFAULT_DRAG_SENSITIVITY } from '../../input-event'
+import { cssLength } from '../_util/css-length'
 
 import { Background } from './Background'
 import { Container } from './Container'
-import { PointsEditorProvider } from './context'
-import { Point } from './Point'
+import { type PointRegistration, PointsEditorProvider } from './context'
+import { AXIS, Point, type PointBaseType } from './Point'
+import { SelectionBox } from './SelectionBox'
+
+import type { CSSVariables } from '../../css-variables'
+
+/** One array for every editor with selection turned off, so memos hold still. */
+const EMPTY: readonly string[] = []
+
+/**
+ * How far a point may move before something in the selection leaves its range.
+ *
+ * Clamping each point on its own would break the shape of the selection: the
+ * one that reached the edge would stop while the rest carried on. One amount
+ * for all of them means the whole selection stops together.
+ */
+function allowedDelta(
+  delta: PointBaseType,
+  entries: { start: PointBaseType; registration: PointRegistration }[],
+): PointBaseType {
+  let loX = -Infinity
+  let hiX = Infinity
+  let loY = -Infinity
+  let hiY = Infinity
+
+  for (const { start, registration } of entries) {
+    loX = Math.max(loX, (registration.min?.x ?? 0) - start.x)
+    hiX = Math.min(hiX, (registration.max?.x ?? 1) - start.x)
+    loY = Math.max(loY, (registration.min?.y ?? 0) - start.y)
+    hiY = Math.min(hiY, (registration.max?.y ?? 1) - start.y)
+  }
+
+  // A point that started outside its own range leaves nothing to move within.
+  return {
+    x: hiX < loX ? 0 : clamp(delta.x, loX, hiX),
+    y: hiY < loY ? 0 : clamp(delta.y, loY, hiY),
+  }
+}
 
 /*
 TODO:
 
-- 複数選択
-- modifier
 - grid
 */
 
@@ -28,43 +77,123 @@ TODO:
  * A point moves over 0..1 in both axes, so a nudge of 0.01 crosses the editor
  * in a hundred steps whatever its pixel size.
  */
-const DEFAULT_INPUT_EVENT_OPTION: InputEventOption = ['normalized', 0.01]
+const DEFAULT_WHEEL: ModifierValue<InputEventOption> = ['normalized', 0.01]
+
+/**
+ * Shift is the fine-adjustment key everywhere else, so it is bound here too
+ * — but only on the keyboard. On the wheel it already means the x axis, and
+ * browsers hand shift+wheel over as horizontal scrolling anyway.
+ */
+const DEFAULT_KEYBOARD: ModifierValue<InputEventOption> = {
+  default: ['normalized', 0.01],
+  shift: ['normalized', 0.001],
+}
 
 export interface PointsEditorProps {
+  /** 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
 
   /**
-   * Only the appearance will change.
-   * Please consider using with readonly.
-   * aria-disabled property is also applied.
+   * Make the points unchangeable and remove them from the tab order.
+   * The parts carry `data-disabled` while it is set.
    */
   disabled?: boolean
   /**
    * Make the points unmovable.
-   * aria-readonly property is also applied.
+   * The parts carry `data-readonly` while it is set.
    */
   readonly?: boolean
 
+  /**
+   * The cursor to show while dragging a point. It is set on the dragged
+   * point, so it stays while the pointer is outside it.
+   *
+   * @default { cursor: 'grabbing' }
+   */
   externalStyles?: {
-    userSelectNone?: boolean
-    cursor?: Cursor
+    cursor?: CSSProperties['cursor']
   }
 
   /**
-   * wheel control option for every `Point`. Shift selects the x axis.
-   * If null, no event will be triggered
+   * How much one notch of the wheel moves the focused `Point`. Scrolling
+   * sideways, or with shift held, moves x; otherwise it moves y.
+   *
+   * A position runs from 0 to 1, so `['normalized', n]` and `['raw', n]` both
+   * move it by `n` of the editor. `null` turns the wheel off, and a `Point`
+   * can override it with a `wheel` of its own.
+   *
+   * @default ['normalized', 0.01]
+   */
+  wheel?: ModifierValue<InputEventOption> | null
+  /**
+   * How much one arrow key press moves a `Point`. Left and right move x, up
+   * and down move y.
+   *
+   * A position runs from 0 to 1, so `['normalized', n]` and `['raw', n]` both
+   * move it by `n` of the editor; give a map to set an amount per modifier
+   * key. `null` turns the arrow keys off, and a `Point` can override it with a
+   * `keyboard` of its own.
+   *
+   * @default { default: ['normalized', 0.01], shift: ['normalized', 0.001] }
+   */
+  keyboard?: ModifierValue<InputEventOption> | null
+
+  /**
+   * How much a drag moves a `Point`, per modifier key.
+   *
+   * `1` is the pointer position itself, which is what dragging a point
+   * normally is. **Anything else turns the drag relative**: `0.1` makes the
+   * same movement cover a tenth of the editor, so the point stops following
+   * the pointer and starts moving a tenth as fast. Shift is bound to `0.1` by
+   * default, to match what it does on the arrow keys.
+   *
+   * Pressing or releasing the key mid-drag does not disturb the point: the
+   * travel so far is kept and the new sensitivity applies from there. **The
+   * pointer and the point stay apart for the rest of the drag** — snapping
+   * them back together on release would move the point nobody asked to move.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  dragSensitivity?: ModifierValue<number>
+
+  /**
+   * Let points be selected, and a selection be moved as one.
+   *
+   * Off by default, because it changes what a press and a drag mean: a press
+   * on empty space starts a selection box rather than doing nothing, and a drag
+   * on a point moves everything else that is selected. An editor whose points
+   * each mean something different — the four handles of an ADSR envelope, say
+   * — has nothing to gain from moving them together.
+   *
+   * **A selection calls `onChange` on several points in the same tick**, so
+   * each of them has to update from the previous state rather than from a
+   * value captured in the render:
+   *
+   * ```jsx
+   * onChange={(v) => setPoints((prev) => ({ ...prev, [id]: v }))}
+   * ```
+   *
+   * Written the other way round — `setPoints({ ...points, [id]: v })` — every
+   * call but the last is thrown away, and only one point appears to move.
    *
-   * A `Point` can override it with a `wheel` of its own.
+   * @default false
    */
-  wheel?: InputEventOption | null
+  selectable?: boolean
+
   /**
-   * keyboard control option for every `Point`, on the arrow keys.
-   * If null, no event will be triggered
+   * Ids of the selected points, to hold the selection yourself. Leave it out
+   * and the editor keeps its own.
    *
-   * A `Point` can override it with a `keyboard` of its own.
+   * A `Point` takes its id from its `id` prop, or generates one that lasts as
+   * long as it is mounted.
    */
-  keyboard?: InputEventOption | null
+  selection?: string[]
+  /** The selection to start with, when the editor keeps its own. */
+  defaultSelection?: string[]
+  /** Called whenever the selection changes, controlled or not. */
+  onSelectionChange?: (selection: string[]) => void
 
   /**
    * The editor renders exactly what you compose here; there is no default
@@ -83,20 +212,27 @@ export interface PointsEditorProps {
    * </PointsEditor.Root>
    */
   children: ReactNode
+
+  style?: CSSProperties & CSSVariables<'width' | 'height'>
 }
 
 type Props = PointsEditorProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorProps>
 
-export const Root = forwardRef<HTMLDivElement, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
-      width = 200,
-      height = 100,
+      width,
+      height,
       disabled = false,
       readonly = false,
-      wheel = DEFAULT_INPUT_EVENT_OPTION,
-      keyboard = DEFAULT_INPUT_EVENT_OPTION,
+      wheel = DEFAULT_WHEEL,
+      keyboard = DEFAULT_KEYBOARD,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      selectable = false,
+      selection: selectionProp,
+      defaultSelection,
+      onSelectionChange,
       externalStyles,
       style,
       className,
@@ -109,7 +245,231 @@ export const Root = forwardRef<HTMLDivElement, Props>(
 
     // Picked apart so that the memo below depends on values rather than on the
     // object literal a caller writes inline, which is new on every render.
-    const { userSelectNone = true, cursor = 'grabbing' } = externalStyles ?? {}
+    const { cursor = 'grabbing' } = externalStyles ?? {}
+
+    // --- selection ---
+    const controlled = selectionProp !== undefined
+    const [ownSelection, setOwnSelection] = useState<string[]>(
+      defaultSelection ?? [],
+    )
+    // Nothing is selected while selection is off, so a drag picks up only the
+    // point it started on and `data-selected` never turns on.
+    const selection = selectable ? (selectionProp ?? ownSelection) : EMPTY
+
+    // Drags read the selection from a native event handler, which runs after
+    // the commit, so a ref is current by the time it matters.
+    const selectionRef = useRef(selection)
+    const changeHandlerRef = useRef(onSelectionChange)
+    useEffect(() => {
+      selectionRef.current = selection
+      changeHandlerRef.current = onSelectionChange
+    })
+
+    const changeSelection = useCallback(
+      (next: string[]) => {
+        selectionRef.current = next
+        if (!controlled) setOwnSelection(next)
+        changeHandlerRef.current?.(next)
+      },
+      [controlled],
+    )
+
+    /**
+     * Every mounted point, by id. A registration is a ref rather than a value:
+     * the value inside changes on every frame of a drag, and a registry keyed
+     * on it would be rebuilt just as often.
+     */
+    const points = useRef(new Map<string, RefObject<PointRegistration>>())
+
+    const registerPoint = useCallback(
+      (id: string, entry: RefObject<PointRegistration>) => {
+        points.current.set(id, entry)
+        return () => {
+          points.current.delete(id)
+        }
+      },
+      [],
+    )
+
+    /** What the current drag picked up, and where those points started. */
+    const dragRef = useRef<{ id: string; start: PointBaseType }[]>([])
+
+    const snapshot = useCallback((ids: readonly string[]) => {
+      return ids.flatMap((id) => {
+        const registration = points.current.get(id)?.current
+        return registration ? [{ id, start: { ...registration.value } }] : []
+      })
+    }, [])
+
+    const applyDeltaTo = useCallback(
+      (
+        entries: { id: string; start: PointBaseType }[],
+        delta: PointBaseType,
+      ) => {
+        const withRegistration = entries.flatMap((entry) => {
+          const registration = points.current.get(entry.id)?.current
+          return registration ? [{ ...entry, registration }] : []
+        })
+        const allowed = allowedDelta(delta, withRegistration)
+        for (const { start, registration } of withRegistration) {
+          if (registration.readonly) continue
+          // Rounded here as well as in the pipeline: a move is a subtraction
+          // and an addition of its own, and that is enough to put the binary
+          // artefact back (0.2 + 0.1 lands on 0.30000000000000004).
+          registration.onChange?.({
+            x: toPrecision(start.x + allowed.x),
+            y: toPrecision(start.y + allowed.y),
+          })
+        }
+      },
+      [],
+    )
+
+    const beginPointDrag = useCallback(
+      (id: string, modifiers: ModifierState) => {
+        if (!selectable) {
+          dragRef.current = snapshot([id])
+          return
+        }
+        const current = selectionRef.current
+        // Ctrl / meta rather than shift: shift is the fine-adjustment key on
+        // every control here, and it cannot be both.
+        const additive = modifiers.ctrlKey || modifiers.metaKey
+        let next: readonly string[]
+        if (additive) {
+          next = current.includes(id)
+            ? current.filter((x) => x !== id)
+            : [...current, id]
+        } else if (current.includes(id)) {
+          // Already part of a group: keep it, so the group can be dragged.
+          next = current
+        } else {
+          next = [id]
+        }
+        changeSelection([...next])
+        // A press that took the point out of the selection was a deselect, not
+        // the start of a move, so there is nothing to drag.
+        dragRef.current = next.includes(id) ? snapshot(next) : []
+      },
+      [selectable, changeSelection, snapshot],
+    )
+
+    const movePointDrag = useCallback(
+      (delta: PointBaseType) => applyDeltaTo(dragRef.current, delta),
+      [applyDeltaTo],
+    )
+
+    const nudgeSelection = useCallback(
+      (id: string, delta: PointBaseType) => {
+        // From wherever the points are now: a key press is not a drag, so
+        // there is no earlier position to measure against.
+        const ids = selectionRef.current.includes(id)
+          ? selectionRef.current
+          : [id]
+        applyDeltaTo(snapshot(ids), delta)
+      },
+      [applyDeltaTo, snapshot],
+    )
+
+    const isPointElement = useCallback(
+      (element: Element | null | undefined) => {
+        if (!element) return false
+        for (const [, entry] of points.current) {
+          if (entry.current.element?.contains(element)) return true
+        }
+        return false
+      },
+      [],
+    )
+
+    const nudgeFocusedPoint = useCallback(
+      (axis: 'x' | 'y', direction: number, modifiers: ModifierState) => {
+        const container = containerRef.current
+        const active = container?.ownerDocument.activeElement
+        if (!container || !active || !container.contains(active)) return false
+        for (const [id, entry] of points.current) {
+          const { element, wheel, readonly, onChange, value } = entry.current
+          // A point answers only for the focus inside its own inputs, so both
+          // axes stay part of the same interaction.
+          if (!element?.contains(active)) continue
+          if (!wheel || readonly || !onChange) return false
+          const next = applyDelta(
+            value[axis],
+            direction,
+            wheel,
+            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,
+          })
+          return true
+        }
+        return false
+      },
+      [nudgeSelection],
+    )
+
+    // --- selection box ---
+    // The box itself lives in the core: which items a rectangle covers, and
+    // what a press adds to or replaces, are not React's to decide. What is
+    // left here is the registry it reads and the state the box is drawn from.
+    const [selectionBox, setSelectionBox] = useState<SelectionBoxRect | null>(
+      null,
+    )
+    const selectionBoxRef = useRef<SelectionBoxInstance<string> | null>(null)
+    selectionBoxRef.current ??= createSelectionBox<string>({
+      *items(): Generator<readonly [string, XY<number>]> {
+        for (const [id, entry] of points.current) {
+          const { x, y } = entry.current.value
+          yield [id, [x, y]]
+        }
+      },
+      onBoxChange: setSelectionBox,
+    })
+
+    // The selection is reported to whoever owns it, and that handler is a new
+    // function whenever the caller's is, so it is handed over rather than
+    // closed over.
+    useEffect(() => {
+      selectionBoxRef.current?.update({ onSelectionChange: changeSelection })
+    }, [changeSelection])
+
+    useEffect(() => {
+      const box = selectionBoxRef.current
+      return () => box?.destroy()
+    }, [])
+
+    const beginSelectionBox = useCallback(
+      (at: PointBaseType, modifiers: ModifierState) => {
+        if (!selectable) return
+        selectionBoxRef.current?.begin([at.x, at.y], {
+          // Ctrl / meta rather than shift: shift is the fine-adjustment key on
+          // every control here, and it cannot be both.
+          additive: modifiers.ctrlKey || modifiers.metaKey,
+          selection: selectionRef.current,
+        })
+      },
+      [selectable],
+    )
+
+    const moveSelectionBox = useCallback((to: PointBaseType) => {
+      selectionBoxRef.current?.move([to.x, to.y])
+    }, [])
+
+    const endSelectionBox = useCallback(() => {
+      if (!selectionBoxRef.current?.end()) return
+      // A selection box is drawn on the container, which is not a control and
+      // cannot hold focus, so the press that started it left the focus on
+      // nothing. The arrow keys and the wheel reach a point only through the
+      // focus, so it is handed to one of the points the box selected —
+      // whichever point takes it moves the whole selection.
+      const [first] = selectionRef.current
+      if (first) points.current.get(first)?.current.element?.focus()
+    }, [])
 
     const context = useMemo(
       () => ({
@@ -117,24 +477,60 @@ export const Root = forwardRef<HTMLDivElement, Props>(
         readonly,
         wheel,
         keyboard,
-        externalStyles: { userSelectNone, cursor },
+        dragSensitivity,
+        externalStyles: { cursor },
         containerRef,
+        selectable,
+        selection,
+        registerPoint,
+        isPointElement,
+        beginPointDrag,
+        movePointDrag,
+        nudgeSelection,
+        nudgeFocusedPoint,
+        selectionBox,
+        beginSelectionBox,
+        moveSelectionBox,
+        endSelectionBox,
       }),
-      [disabled, readonly, wheel, keyboard, userSelectNone, cursor],
+      [
+        disabled,
+        readonly,
+        wheel,
+        keyboard,
+        dragSensitivity,
+        cursor,
+        selectable,
+        selection,
+        registerPoint,
+        isPointElement,
+        beginPointDrag,
+        movePointDrag,
+        nudgeSelection,
+        nudgeFocusedPoint,
+        selectionBox,
+        beginSelectionBox,
+        moveSelectionBox,
+        endSelectionBox,
+      ],
     )
 
     return (
       <PointsEditorProvider value={context}>
         <div
           ref={forwardedRef}
-          className={clsx('tremolo-points-editor', className)}
-          aria-disabled={disabled}
-          aria-readonly={readonly}
-          style={{
-            width,
-            height,
-            ...style,
-          }}
+          className={className}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          style={
+            {
+              '--width': cssLength(width),
+              '--height': cssLength(height),
+              // The layers inside are placed against this box.
+              position: 'relative',
+              ...style,
+            } as CSSProperties
+          }
           {...props}
         >
           {children}
@@ -152,12 +548,15 @@ export const PointsEditor = {
   Background,
   Container,
   Point,
+  SelectionBox,
 }
 
 export {
   usePointsEditorContext,
   type PointsEditorContextValue,
 } from './context'
-export { type PointsEditorBackgroundProps } from './Background'
-export { type PointsEditorContainerProps } from './Container'
-export { clampPoint, type PointBaseType, type PointProps } from './Point'
+export {
+  clampPoint,
+  type PointBaseType,
+  type PointsEditorPointProps,
+} from './Point'