@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/PointsEditor/index.tsx

@@ -1,88 +1,238 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, forwardRef } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  forwardRef,
+  ReactNode,
+  RefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 
-import { InputEventOption } from '@tremolo-ui/functions'
+import {
+  createSelectionBox,
+  type SelectionBoxInstance,
+  type SelectionBoxRect,
+  type XY,
+} from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  clamp,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  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, PointBaseType } from './Point'
+import { type PointRegistration, PointsEditorProvider } from './context'
+import { AXIS, Point, type PointBaseType } from './Point'
+import { SelectionBox } from './SelectionBox'
+
+/** 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
 */
 
-/*
-import { useState } from 'react'
-
-export default function App() {
-  const [points, setPoints] = useState(initialPoints)
-
-  return (
-    <PointsEditor.Root
-      onDoubleClick={({ x, y }, _e) => {
-        const newPoints = [...points, { x, y }]
-        setPoints(newPoints)
-      }}
-    >
-      {points.map((point) => (
-        <PointsEditor.Point key={`${point.x}, ${point.y}`} value={point} />
-      ))}
-    </PointsEditor.Root>
-  )
-}
-*/
+/**
+ * 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_WHEEL: ModifierValue<InputEventOption> = ['normalized', 0.01]
 
-const defaultExternalStyles: PointsEditorProps['externalStyles'] = {
-  userSelectNone: true,
-  cursor: 'grabbing',
+/**
+ * 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
 
-  // TODO
-  grid?: number | PointBaseType
-  // modifier?:
-
+  /**
+   * 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.
+   * 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']
   }
 
-  // TODO
   /**
-   * wheel control option
-   * 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.
+   *
+   * @default false
+   */
+  selectable?: boolean
+
+  /**
+   * Ids of the selected points, to hold the selection yourself. Leave it out
+   * and the editor keeps its own.
+   *
+   * A `Point` takes its id from its `id` prop, or generates one that lasts as
+   * long as it is mounted.
    */
-  wheel?: 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
+
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * The editor renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <PointsEditor.Root>
+   *   <PointsEditor.Background>
+   *     <svg viewBox="0 0 200 100">...</svg>
+   *   </PointsEditor.Background>
+   *   <PointsEditor.Container>
+   *     {points.map((point, i) => (
+   *       <PointsEditor.Point key={i} value={point} onChange={...} />
+   *     ))}
+   *   </PointsEditor.Container>
+   * </PointsEditor.Root>
    */
-  keyboard?: InputEventOption | null
+  children: ReactNode
 }
 
 type Props = PointsEditorProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorProps>
 
-const Root = forwardRef<HTMLDivElement, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
-      width = 200,
-      height = 100,
+      width,
+      height,
       disabled = false,
       readonly = false,
-      externalStyles: _externalStyles,
+      wheel = DEFAULT_WHEEL,
+      keyboard = DEFAULT_KEYBOARD,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      selectable = false,
+      selection: selectionProp,
+      defaultSelection,
+      onSelectionChange,
+      externalStyles,
       style,
       className,
       children,
@@ -90,22 +240,296 @@ const Root = forwardRef<HTMLDivElement, Props>(
     },
     forwardedRef,
   ) => {
-    const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
+    const containerRef = useRef<HTMLDivElement>(null)
+
+    // 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 { 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(
+      () => ({
+        disabled,
+        readonly,
+        wheel,
+        keyboard,
+        dragSensitivity,
+        externalStyles: { cursor },
+        containerRef,
+        selectable,
+        selection,
+        registerPoint,
+        isPointElement,
+        beginPointDrag,
+        movePointDrag,
+        nudgeSelection,
+        nudgeFocusedPoint,
+        selectionBox,
+        beginSelectionBox,
+        moveSelectionBox,
+        endSelectionBox,
+      }),
+      [
+        disabled,
+        readonly,
+        wheel,
+        keyboard,
+        dragSensitivity,
+        cursor,
+        selectable,
+        selection,
+        registerPoint,
+        isPointElement,
+        beginPointDrag,
+        movePointDrag,
+        nudgeSelection,
+        nudgeFocusedPoint,
+        selectionBox,
+        beginSelectionBox,
+        moveSelectionBox,
+        endSelectionBox,
+      ],
+    )
 
     return (
-      <PointsEditorProvider
-        disabled={disabled}
-        readonly={readonly}
-        externalStyles={externalStyles}
-      >
+      <PointsEditorProvider value={context}>
         <div
           ref={forwardedRef}
-          className={clsx('tremolo-points-editor', className)}
-          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}
@@ -123,7 +547,18 @@ export const PointsEditor = {
   Background,
   Container,
   Point,
+  SelectionBox,
 }
 
-export { usePointsEditorContext } from './context'
-export { clampPoint, type PointBaseType, type PointProps } from './Point'
+export {
+  usePointsEditorContext,
+  type PointsEditorContextValue,
+} from './context'
+export { type PointsEditorBackgroundProps } from './Background'
+export { type PointsEditorContainerProps } from './Container'
+export { type PointsEditorSelectionBoxProps } from './SelectionBox'
+export {
+  clampPoint,
+  type PointBaseType,
+  type PointsEditorPointProps,
+} from './Point'

package/src/components/Slider/Marks.tsx

@@ -0,0 +1,84 @@
+import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
+
+import { xor } from '@tremolo-ui/functions'
+
+import { cssLength } from '../_util/css-length'
+import { Placement } from '../_util/Placement'
+
+import { useSliderContext } from './context'
+import { MarksOption } from './MarksOption'
+import { generateOptionsList, MarksOptions } from './type'
+
+export interface SliderMarksProps {
+  /**
+   * Space between the marks and the track. Sets `--gap`; the theme's own
+   * spacing stands when this is omitted.
+   */
+  gap?: number | string
+  /**
+   * Build the marks instead of writing `Slider.MarksOption` out: a number puts
+   * one every that many, `'step'` one every `step`, and `{ per, mark, label }`
+   * also turns the mark or the label off for all of them. `children` is
+   * ignored while it is set.
+   *
+   * `'step'` makes one per step, which is a great many for a fine `step`.
+   */
+  options?: MarksOptions
+  /**
+   * `<Slider.MarksOption />` goes here, one per mark. Ignored while `options`
+   * is set.
+   */
+  children?: ReactNode
+}
+
+export function Marks({
+  gap,
+  options,
+  children,
+  className,
+  style,
+  ...props
+}: SliderMarksProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof SliderMarksProps>) {
+  const min = useSliderContext((s) => s.min)
+  const max = useSliderContext((s) => s.max)
+  const step = useSliderContext((s) => s.step)
+  const vertical = useSliderContext((s) => s.vertical)
+  const reverse = useSliderContext((s) => s.reverse)
+
+  const optionsList = options
+    ? generateOptionsList(options, min, max, step)
+    : []
+  if (xor(vertical, reverse)) optionsList.reverse()
+
+  return (
+    <div
+      className={className}
+      data-orientation={vertical ? 'vertical' : 'horizontal'}
+      style={
+        {
+          '--gap': cssLength(gap),
+          // Each option inside is placed against this box.
+          position: 'relative',
+          ...style,
+        } as CSSProperties
+      }
+      {...props}
+    >
+      <Placement name="Slider.Marks">
+        {options
+          ? optionsList.map(({ value, mark, label }, index) => {
+              return (
+                <MarksOption
+                  key={index}
+                  value={value}
+                  mark={mark}
+                  label={label ? undefined : null}
+                />
+              )
+            })
+          : children}
+      </Placement>
+    </div>
+  )
+}