@tremolo-ui/dom 0.7.0 → 0.9.0

package/src/points-editor/index.ts

@@ -0,0 +1,367 @@
+import { clamp, toPrecision } from '@tremolo-ui/functions'
+
+import { applyDelta } from '../input/apply-delta'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from '../input/modifiers'
+import { createSelectionBox, type SelectionBoxRect } from '../selection/box'
+import { type XY } from '../xy'
+
+/** Where a point is: 0..1 on each axis, with y growing downwards. */
+export interface PointPosition {
+  x: number
+  y: number
+}
+
+/**
+ * A point's value is its position in the editor, so its range is the editor:
+ * no scaling, and no rounding to a step.
+ */
+export const POINT_AXIS = { min: 0, max: 1 }
+
+/**
+ * How much one wheel notch moves a point by default: a hundredth of the
+ * editor, whatever its pixel size.
+ */
+export const POINTS_EDITOR_DEFAULT_WHEEL: ModifierValue<InputEventOption> = [
+  'normalized',
+  0.01,
+]
+
+/**
+ * How much one arrow key press moves a point by default. 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.
+ */
+export const POINTS_EDITOR_DEFAULT_KEYBOARD: ModifierValue<InputEventOption> = {
+  default: ['normalized', 0.01],
+  shift: ['normalized', 0.001],
+}
+
+/** Keep a point within its range. An axis left out runs from 0 to 1. */
+export function clampPoint(
+  point: PointPosition,
+  min?: Partial<PointPosition>,
+  max?: Partial<PointPosition>,
+): PointPosition {
+  return {
+    x: clamp(point.x, min?.x ?? 0, max?.x ?? 1),
+    y: clamp(point.y, min?.y ?? 0, max?.y ?? 1),
+  }
+}
+
+/**
+ * What a point tells the editor about itself, so that a selection can be
+ * moved without the editor knowing how the points are stored.
+ */
+export interface PointsEditorPoint {
+  value: PointPosition
+  min?: Partial<PointPosition>
+  max?: Partial<PointPosition>
+  /** A point that cannot move stays put while the rest of a selection moves. */
+  readonly?: boolean
+  onChange?: (value: PointPosition) => void
+  /** The point's own element, to match the focus and a press against. */
+  element?: Element | null
+  /** The wheel option the point resolved, `null` for no wheel. */
+  wheel?: ModifierValue<InputEventOption> | null
+  /**
+   * Called just before the wheel moves this point as the focused one, so that
+   * it can report its change as started before the value arrives.
+   */
+  beforeWheel?: () => void
+}
+
+export interface PointsEditorOptions {
+  /**
+   * Let points be selected, and a selection be moved as one. While it is off
+   * nothing is selected, and a drag moves only the point it started on.
+   *
+   * @default false
+   */
+  selectable?: boolean
+  /**
+   * The ids of the selected points. Whoever holds the selection pushes it
+   * back with `update()` after {@link PointsEditorOptions.onSelectionChange}.
+   */
+  selection?: readonly string[]
+  /** Called whenever a press or a selection box changes the selection. */
+  onSelectionChange?: (selection: string[]) => void
+  /** Called whenever the selection box changes, with `null` once it is gone. */
+  onSelectionBoxChange?: (rect: SelectionBoxRect | null) => void
+}
+
+export interface PointsEditorInstance {
+  /** Replace the given options. */
+  update: (options: Partial<PointsEditorOptions>) => void
+  /**
+   * Register a point under `id`. `read` is called whenever the editor needs
+   * the point, so it can return what the point is now rather than what it
+   * was when it registered. Returns the function that unregisters it.
+   */
+  registerPoint: (id: string, read: () => PointsEditorPoint) => () => void
+  /** Whether the element is a point, or inside one. */
+  isPointElement: (element: Element | null | undefined) => boolean
+  /**
+   * A pointer went down on a point: work out the new selection and remember
+   * where everything the drag picked up started.
+   *
+   * Ctrl / meta add the point to the selection or take it out: shift is the
+   * fine-adjustment key on every control here, and it cannot be both. A
+   * press on a point already selected keeps the selection, so the group can
+   * be dragged.
+   */
+  beginPointDrag: (id: string, modifiers: ModifierState) => void
+  /**
+   * Move everything the drag picked up by `delta` from where it started,
+   * stopping the whole group together at the edge.
+   */
+  movePointDrag: (delta: PointPosition) => void
+  /**
+   * Move `id` — and the selection, when it is part of one — by `delta` from
+   * where the points are now: an input that is not a drag has no earlier
+   * position to measure against.
+   */
+  nudgeSelection: (id: string, delta: PointPosition) => void
+  /**
+   * Move `id` by one press of `option` along one axis, taking the selection
+   * along as {@link PointsEditorInstance.nudgeSelection} does.
+   */
+  nudgePoint: (
+    id: string,
+    axis: 'x' | 'y',
+    direction: number,
+    option: ModifierValue<InputEventOption>,
+    modifiers?: ModifierState,
+  ) => void
+  /**
+   * Move the point holding the focus by one wheel notch, with its own wheel
+   * option. The wheel is listened to once for the whole editor, since a wheel
+   * event only reaches what the cursor is over. Returns whether a point took
+   * it, so the caller knows whether to consume the event.
+   */
+  nudgeFocusedPoint: (
+    axis: 'x' | 'y',
+    direction: number,
+    modifiers: ModifierState,
+  ) => boolean
+  /** A drag on empty space started at `at`: start a selection box there. */
+  beginSelectionBox: (at: PointPosition, modifiers: ModifierState) => void
+  moveSelectionBox: (to: PointPosition) => void
+  /**
+   * End the selection box. The press that started it left the focus on
+   * nothing, and 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.
+   */
+  endSelectionBox: () => void
+  destroy: () => void
+}
+
+const EMPTY: readonly string[] = []
+
+/**
+ * How far a group may move before something in it 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: PointPosition,
+  entries: { start: PointPosition; point: PointsEditorPoint }[],
+): PointPosition {
+  let loX = -Infinity
+  let hiX = Infinity
+  let loY = -Infinity
+  let hiY = Infinity
+  for (const { start, point } of entries) {
+    // A point that cannot move stays where it is, so its range says nothing
+    // about how far the rest may go.
+    if (point.readonly) continue
+    loX = Math.max(loX, (point.min?.x ?? 0) - start.x)
+    hiX = Math.min(hiX, (point.max?.x ?? 1) - start.x)
+    loY = Math.max(loY, (point.min?.y ?? 0) - start.y)
+    hiY = Math.min(hiY, (point.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),
+  }
+}
+
+/**
+ * The selection and the moves of a points editor: which points a press or a
+ * box selects, and how a selection moves as one.
+ *
+ * The points stay with the wrapper, which registers each one; the editor only
+ * reads them when it needs to, so a point's value can change on every frame
+ * of a drag without anything being re-registered.
+ */
+export function createPointsEditor(
+  options: PointsEditorOptions = {},
+): PointsEditorInstance {
+  let opts = options
+  const points = new Map<string, () => PointsEditorPoint>()
+  /** What the current drag picked up, and where those points started. */
+  let dragged: { id: string; start: PointPosition }[] = []
+
+  const selection = () => (opts.selectable ? (opts.selection ?? EMPTY) : EMPTY)
+
+  function changeSelection(next: string[]) {
+    // Read back at once by the drag that follows, before the owner has had a
+    // chance to push it with update().
+    opts = { ...opts, selection: next }
+    opts.onSelectionChange?.(next)
+  }
+
+  function snapshot(ids: readonly string[]) {
+    return ids.flatMap((id) => {
+      const point = points.get(id)?.()
+      return point ? [{ id, start: { ...point.value } }] : []
+    })
+  }
+
+  function moveFrom(
+    entries: { id: string; start: PointPosition }[],
+    delta: PointPosition,
+  ) {
+    const withPoint = entries.flatMap((entry) => {
+      const point = points.get(entry.id)?.()
+      return point ? [{ ...entry, point }] : []
+    })
+    const allowed = allowedDelta(delta, withPoint)
+    for (const { start, point } of withPoint) {
+      if (point.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).
+      point.onChange?.({
+        x: toPrecision(start.x + allowed.x),
+        y: toPrecision(start.y + allowed.y),
+      })
+    }
+  }
+
+  function nudgeSelection(id: string, delta: PointPosition) {
+    const current = selection()
+    moveFrom(snapshot(current.includes(id) ? current : [id]), delta)
+  }
+
+  function nudgePoint(
+    id: string,
+    axis: 'x' | 'y',
+    direction: number,
+    option: ModifierValue<InputEventOption>,
+    modifiers?: ModifierState,
+  ) {
+    const point = points.get(id)?.()
+    if (!point) return
+    const { value } = point
+    const next = applyDelta(
+      value[axis],
+      direction,
+      option,
+      POINT_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,
+    })
+  }
+
+  const box = createSelectionBox<string>({
+    *items(): Generator<readonly [string, XY<number>]> {
+      for (const [id, read] of points) {
+        const { x, y } = read().value
+        yield [id, [x, y]]
+      }
+    },
+    onBoxChange: (rect) => opts.onSelectionBoxChange?.(rect),
+    onSelectionChange: changeSelection,
+  })
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    registerPoint: (id, read) => {
+      points.set(id, read)
+      return () => {
+        if (points.get(id) === read) points.delete(id)
+      }
+    },
+    isPointElement: (element) => {
+      if (!element) return false
+      for (const read of points.values()) {
+        if (read().element?.contains(element)) return true
+      }
+      return false
+    },
+    beginPointDrag: (id, modifiers) => {
+      if (!opts.selectable) {
+        dragged = snapshot([id])
+        return
+      }
+      const current = selection()
+      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)) {
+        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.
+      dragged = next.includes(id) ? snapshot(next) : []
+    },
+    movePointDrag: (delta) => moveFrom(dragged, delta),
+    nudgeSelection,
+    nudgePoint,
+    nudgeFocusedPoint: (axis, direction, modifiers) => {
+      for (const [id, read] of points) {
+        const { element, wheel, readonly, onChange, beforeWheel } = read()
+        // The document the point is in, which need not be the one this script
+        // runs in — an editor rendered into an iframe has its own focus.
+        const active = element?.ownerDocument.activeElement
+        // A point answers only for the focus inside its own inputs, so both
+        // axes stay part of the same interaction.
+        if (!active || !element?.contains(active)) continue
+        if (!wheel || readonly || !onChange) return false
+        beforeWheel?.()
+        nudgePoint(id, axis, direction, wheel, modifiers)
+        return true
+      }
+      return false
+    },
+    beginSelectionBox: (at, modifiers) => {
+      if (!opts.selectable) return
+      box.begin([at.x, at.y], {
+        additive: modifiers.ctrlKey || modifiers.metaKey,
+        selection: selection(),
+      })
+    },
+    moveSelectionBox: (to) => box.move([to.x, to.y]),
+    endSelectionBox: () => {
+      if (!box.end()) return
+      const [first] = selection()
+      const element = first ? points.get(first)?.().element : null
+      if (element && 'focus' in element) (element as HTMLElement).focus()
+    },
+    destroy: () => {
+      box.destroy()
+      dragged = []
+    },
+  }
+}

package/src/position.ts

@@ -0,0 +1,20 @@
+import { linearScale, toFixed, type ValueRange } from '@tremolo-ui/functions'
+
+/**
+ * Where a value sits along a track, as a whole percentage from its start.
+ *
+ * Normalized along the scale, so a thumb, the fill behind it and the marks
+ * all sit on the curve the drag follows. `reversed` measures from the other
+ * end — for a track that grows upwards or leftwards on screen, since CSS
+ * places things from the top and the left.
+ */
+export function valuePercent(
+  value: number,
+  { min, max, scale = linearScale }: Pick<ValueRange, 'min' | 'max' | 'scale'>,
+  reversed = false,
+): number {
+  // Reversed before rounding, so that a value halfway between two whole
+  // percentages lands on the same one whichever end it is measured from.
+  const normalized = scale.normalize(value, min, max)
+  return toFixed((reversed ? 1 - normalized : normalized) * 100)
+}

package/src/slider/decimal-digits.ts

@@ -0,0 +1,23 @@
+/**
+ * How many digits a number carries after the decimal point.
+ *
+ * `Slider.Marks` builds its labels by multiplying an interval, which leaves
+ * binary debris in the last digits (`0.1 * 3` is `0.30000000000000004`). The
+ * count is what tells `toFixed` how far to round that back.
+ *
+ * The exponent form has to be handled separately: `String(1e-7)` is `'1e-7'`,
+ * which has no decimal point at all, so reading the text after the point
+ * reports no digits and the interval rounds away to whole numbers.
+ */
+export function decimalDigits(x: number): number {
+  if (!Number.isFinite(x)) return 0
+
+  const text = String(x)
+  const e = text.indexOf('e')
+  if (e === -1) return text.split('.')[1]?.length ?? 0
+
+  const fraction = text.slice(0, e).split('.')[1]?.length ?? 0
+  // A negative exponent pushes the point further right, a positive one pulls
+  // it back past the digits that are there.
+  return Math.max(0, fraction - Number(text.slice(e + 1)))
+}

package/src/slider/marks.ts

@@ -0,0 +1,56 @@
+import { toFixed } from '@tremolo-ui/functions'
+
+import { decimalDigits } from './decimal-digits'
+
+/**
+ * How `Slider.Marks` fills itself in when it is given no children: one option
+ * every `per`, or every `step` of the slider. The object form turns off the
+ * mark or the label for the whole set; a single option is customized by
+ * writing `Slider.MarksOption` out instead.
+ */
+export type MarksOptions =
+  | 'step'
+  | number
+  | {
+      per: 'step' | number
+      mark?: boolean
+      label?: boolean
+    }
+
+/** One mark along a slider, as {@link sliderMarks} lays them out. */
+export interface SliderMark {
+  value: number
+  mark: boolean
+  label: boolean
+}
+
+/**
+ * The marks `options` asks for between `min` and `max`, in ascending order.
+ *
+ * Each value is a whole multiple of the interval, rounded to the digits the
+ * interval has: stepping by 0.1 would otherwise put binary debris in the
+ * labels (`0.1 * 3` is `0.30000000000000004`).
+ */
+export function sliderMarks(
+  options: MarksOptions,
+  min: number,
+  max: number,
+  step: number,
+): SliderMark[] {
+  const {
+    per,
+    mark = true,
+    label = true,
+  } = typeof options === 'object' ? options : { per: options }
+  const optionsList: SliderMark[] = []
+  const interval = per === 'step' ? step : per
+  const count = Math.floor(max / interval) - Math.ceil(min / interval) + 1
+  for (let i = 0; i < count; i++) {
+    const value = toFixed(
+      interval * (Math.ceil(min / interval) + i),
+      decimalDigits(interval),
+    )
+    optionsList.push({ value: value, mark: mark, label: label })
+  }
+  return optionsList
+}

package/src/style.ts

@@ -0,0 +1,41 @@
+/**
+ * A number as a CSS length, for a custom property.
+ *
+ * A custom property takes whatever text it is given, so `--size: 50` comes out
+ * as the invalid `50` rather than `50px`. React appends `px` to a bare number
+ * only for the properties it knows take a length, and a custom property is
+ * never one of them; Vue and Svelte append nothing at all. Anything already a
+ * string is passed through, so `'3rem'` and `'100%'` still work.
+ */
+export function cssLength(
+  value: number | string | undefined,
+): string | undefined {
+  return typeof value === 'number' ? `${value}px` : value
+}
+
+/**
+ * Take an element out of sight while leaving it in the accessibility tree and
+ * in the tab order.
+ *
+ * `display: none` and `visibility: hidden` would remove it from both, and the
+ * native control underneath a headless component is what carries the ARIA and
+ * the keyboard behaviour. `pointer-events: none` is safe because nothing is
+ * ever clicked here directly: a `<label>` forwards its click, and a drag is
+ * handled by the part that is visible.
+ *
+ * Every value is a string with its unit, so the object can be handed to any
+ * framework's `style` binding as it is.
+ */
+export const visuallyHiddenStyle = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  clipPath: 'inset(50%)',
+  whiteSpace: 'nowrap',
+  border: '0',
+  pointerEvents: 'none',
+} as const