@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/Piano/keyboard-shortcuts.ts

@@ -0,0 +1,61 @@
+export type KeyboardShortcuts = {
+  /**
+   * Keys laid out from `noteRange.first`, one entry per semitone.
+   *
+   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
+   * never empty, so the entry can never match. Use it to skip the black keys
+   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
+   * lined up with the notes.
+   */
+  keys: string[]
+}
+
+/**
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
+ */
+export const SHORTCUTS = {
+  /** Every semitone from C, over the two rows of a QWERTY keyboard. */
+  HOME_ROW: {
+    keys: [
+      'a',
+      'w',
+      's',
+      'e',
+      'd',
+      'f',
+      't',
+      'g',
+      'y',
+      'h',
+      'u',
+      'j',
+      'k',
+      'o',
+      'l',
+      'p',
+      ';',
+    ],
+  },
+  /** The white keys only, on the home row. Black keys have no shortcut. */
+  HOME_ROW_NATURAL: {
+    keys: [
+      'a',
+      '',
+      's',
+      '',
+      'd',
+      'f',
+      '',
+      'g',
+      '',
+      'h',
+      '',
+      'j',
+      'k',
+      '',
+      'l',
+      '',
+      ';',
+    ],
+  },
+}

package/src/components/PointsEditor/Background.tsx

@@ -1,14 +1,29 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef } from 'react'
+import { ComponentPropsWithoutRef, ReactNode } from 'react'
+
+export interface PointsEditorBackgroundProps {
+  /** Whatever the points are placed over: a graph, a canvas, an image. */
+  children?: ReactNode
+}
 
 export function Background({
   className,
   children,
+  style,
   ...props
-}: ComponentPropsWithoutRef<'div'>) {
+}: PointsEditorBackgroundProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorBackgroundProps>) {
   return (
     <div
-      className={clsx('tremolo-points-editor-background', className)}
+      className={className}
+      style={{
+        // Behind the points, filling the editor: what it is for, rather than
+        // a look. The order of the layers holds whichever way they are
+        // written, so the z-index is part of the same mechanics.
+        position: 'absolute',
+        inset: 0,
+        zIndex: 0,
+        ...style,
+      }}
       {...props}
     >
       {children}

package/src/components/PointsEditor/Container.tsx

@@ -1,26 +1,96 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, useRef } from 'react'
+import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
+
+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 function Container({
-  className,
-  children,
-  ...props
-}: ComponentPropsWithoutRef<'div'>) {
-  const containerElementRef = useRef<HTMLDivElement>(null)
-  const setContainerElementRef = usePointsEditorContext(
-    (s) => s.setContainerElementRef,
-  )
-  setContainerElementRef(containerElementRef)
-
-  return (
-    <div
-      ref={containerElementRef}
-      className={clsx('tremolo-points-editor-container', className)}
-      {...props}
-    >
-      {children}
-    </div>
-  )
+export interface PointsEditorContainerProps {
+  /** `<PointsEditor.Point />` goes here. */
+  children?: ReactNode
 }
+
+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,12 +1,30 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
 
-import { clamp } from '@tremolo-ui/functions'
+import {
+  applyDelta,
+  clamp,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  selectModifier,
+} from '@tremolo-ui/functions'
 
-import { useDragWithElement } from '../../hooks/useDragWithElement'
-import { addUserSelectNone, removeUserSelectNone } from '../_util'
+import { useComposedRefs } from '../../compose-refs'
+import { useDragValue } from '../../hooks/useDragValue'
+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 }
 
@@ -21,35 +39,97 @@ 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`. */
   disabled?: boolean
+  /** Overrides the `readonly` of `PointsEditor.Root`. */
   readonly?: boolean
 
+  /** Overrides the `wheel` of `PointsEditor.Root`. */
+  wheel?: ModifierValue<InputEventOption> | null
+  /** Overrides the `keyboard` of `PointsEditor.Root`. */
+  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
 }
 
+/**
+ * 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.
+ */
+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,
-  readonly,
+  disabled: _disabled,
+  readonly: _readonly,
+  wheel: _wheel,
+  keyboard: _keyboard,
+  'aria-label': ariaLabel,
+  'aria-valuetext': ariaValuetext,
 
   onChange,
   onDragStart,
@@ -58,65 +138,225 @@ export function Point<T extends PointBaseType>({
   className,
   style,
   onPointerDown,
+  onKeyDown,
+  onFocus,
   ...props
-}: PointProps<T> & Omit<ComponentPropsWithoutRef<'div'>, keyof PointProps<T>>) {
-  const containerElementRef = usePointsEditorContext(
-    (s) => s.containerElementRef,
-  )
-  const externalStyles = usePointsEditorContext((s) => s.externalStyles)
-  const __disabled = usePointsEditorContext((s) => s.disabled)
-  const __readonly = usePointsEditorContext((s) => s.readonly)
+}: PointsEditorPointProps<T> &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>) {
+  const {
+    containerRef,
+    externalStyles,
+    disabled: rootDisabled,
+    readonly: rootReadonly,
+    wheel: rootWheel,
+    keyboard: rootKeyboard,
+    dragSensitivity,
+    selection,
+    registerPoint,
+    beginPointDrag,
+    movePointDrag,
+    nudgeSelection,
+  } = usePointsEditorContext()
 
-  // console.log(value.x, value.y)
+  const generatedId = useId()
+  const id = idProp ?? generatedId
+  const selected = selection.includes(id)
 
-  // Piano: 値が更新されることで、イベントハンドラがリセットされる
+  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
 
-  const { refCallback: dragRefCallback, dragging } =
-    useDragWithElement<HTMLDivElement>({
-      baseElementRef: containerElementRef,
-      cursor: readonly ? undefined : externalStyles.cursor,
-      onDrag: (x, y) => {
-        if (readonly) return
+  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])
 
-        onChange?.(clampPoint({ x, y }, min, max))
+  /** 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,
+      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]) => {
+        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 colors: Record<string, string | undefined> = {
-    '--color': color,
+  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'
+    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 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.
+    // oxlint-disable-next-line jsx-a11y/no-static-element-interactions
     <div
-      ref={dragRefCallback}
-      className={clsx('tremolo-points-editor-point', className)}
-      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
-      tabIndex={0}
-      aria-disabled={disabled != undefined ? disabled : __disabled}
-      aria-readonly={readonly != undefined ? readonly : __readonly}
-      data-dragging={dragging}
-      style={{
-        ...colors,
-        width: size ?? width,
-        height: size ?? height,
-        left: `${value.x * 100}%`,
-        top: `${value.y * 100}%`,
-        ...style,
-      }}
+      ref={refCallback}
+      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>
+  )
+}