@tremolo-ui/dom 0.4.0 → 0.6.0

package/src/selection/box.ts

@@ -0,0 +1,136 @@
+import type { XY } from '../xy'
+
+/**
+ * A rectangle in the 0..1 space of whatever the box is drawn over, with `y`
+ * growing downwards — the same space the items are given in.
+ */
+export interface SelectionBoxRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface SelectionBoxOptions<Id> {
+  /**
+   * Everything the box can pick up, read on every move rather than taken as a
+   * snapshot: what is under the box changes while it is dragged, and an item
+   * may have moved since the last one.
+   */
+  items: () => Iterable<readonly [Id, XY<number>]>
+  /** The box as it is dragged, and `null` once it is gone. */
+  onBoxChange?: (box: SelectionBoxRect | null) => void
+  /** What the box covers, added to whatever it started from. */
+  onSelectionChange?: (ids: Id[]) => void
+}
+
+export interface SelectionBoxBeginOptions<Id> {
+  /**
+   * Add to `selection` rather than replacing it. Ctrl / meta rather than
+   * shift, for the controls where shift is the fine-adjustment key.
+   */
+  additive?: boolean
+  /** What was selected before the box started. Only read when `additive`. */
+  selection?: readonly Id[]
+}
+
+export interface SelectionBoxInstance<Id> {
+  /** Replace the given options, without interrupting a box in progress. */
+  update: (options: Partial<SelectionBoxOptions<Id>>) => void
+
+  /** Start a box at `at`, which is one of its corners. */
+  begin: (at: XY<number>, options?: SelectionBoxBeginOptions<Id>) => void
+  /** Drag the opposite corner to `to`. */
+  move: (to: XY<number>) => void
+  /**
+   * Finish the box. The selection stays as it is.
+   *
+   * @returns whether a box was running, so that a caller can tell a drag from
+   *   a press that selected nothing.
+   */
+  end: () => boolean
+
+  /** The box being dragged, or `null` when there is none. */
+  box: () => SelectionBoxRect | null
+
+  destroy: () => void
+}
+
+function rectOf(from: XY<number>, to: XY<number>): SelectionBoxRect {
+  return {
+    x: Math.min(from[0], to[0]),
+    y: Math.min(from[1], to[1]),
+    width: Math.abs(to[0] - from[0]),
+    height: Math.abs(to[1] - from[1]),
+  }
+}
+
+/** Whether the box covers the point, edges included. */
+export function selectionBoxCovers(
+  box: SelectionBoxRect,
+  [x, y]: XY<number>,
+): boolean {
+  return (
+    x >= box.x &&
+    x <= box.x + box.width &&
+    y >= box.y &&
+    y <= box.y + box.height
+  )
+}
+
+/**
+ * Selecting by dragging a box over a set of items.
+ *
+ * The drag itself is not here: the caller owns the pointer, and reports where
+ * it went in the same 0..1 space the items are given in.
+ */
+export function createSelectionBox<Id>(
+  options: SelectionBoxOptions<Id>,
+): SelectionBoxInstance<Id> {
+  let opts = options
+  let drag: { from: XY<number>; base: readonly Id[] } | null = null
+  let box: SelectionBoxRect | null = null
+
+  function setBox(next: SelectionBoxRect | null) {
+    box = next
+    opts.onBoxChange?.(next)
+  }
+
+  function apply(rect: SelectionBoxRect, base: readonly Id[]) {
+    const inside: Id[] = []
+    for (const [id, at] of opts.items()) {
+      if (selectionBoxCovers(rect, at) && !base.includes(id)) inside.push(id)
+    }
+    opts.onSelectionChange?.([...base, ...inside])
+  }
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    begin: (at, { additive = false, selection = [] } = {}) => {
+      drag = { from: at, base: additive ? [...selection] : [] }
+      setBox(rectOf(at, at))
+      // A plain press is a deselect of its own, so that a drag that picks
+      // nothing up leaves nothing selected.
+      if (!additive) opts.onSelectionChange?.([])
+    },
+    move: (to) => {
+      if (!drag) return
+      const rect = rectOf(drag.from, to)
+      setBox(rect)
+      apply(rect, drag.base)
+    },
+    end: () => {
+      const running = drag !== null
+      drag = null
+      if (box !== null) setBox(null)
+      return running
+    },
+    box: () => box,
+    destroy: () => {
+      drag = null
+      box = null
+    },
+  }
+}

package/src/xy.ts

@@ -0,0 +1,38 @@
+/**
+ * A pair of per-axis values. The tuple elements are labelled, so editors show
+ * `[x: number, y: number]` rather than a bare pair.
+ */
+export type XY<T> = [x: T, y: T]
+
+/**
+ * A setting that may be given once for both axes, or per axis.
+ *
+ * A single value is told from a pair with `Array.isArray`, so the single form
+ * is only offered while `T` cannot itself be an array. Where it can, the pair
+ * is the only way to write it, since a lone array would be read as a pair.
+ */
+export type XYInput<T> = [T] extends [readonly unknown[]]
+  ? readonly [x: T, y: T]
+  : T | readonly [x: T, y: T]
+
+// `Array.isArray` narrows a mutable tuple on its own, but not a readonly one,
+// hence the explicit predicate.
+function isPair<T>(
+  value: T | readonly [x: T, y: T],
+): value is readonly [x: T, y: T] {
+  return Array.isArray(value)
+}
+
+/**
+ * Spread a setting that may have been given as a single value.
+ *
+ * The parameter is written out rather than taken as `XYInput<T>`: a
+ * conditional type cannot be narrowed, so the constraint stays where it is
+ * declared and this takes both forms.
+ *
+ * The pair is copied rather than passed along, so that the result is a tuple
+ * the caller owns even when a readonly one was given.
+ */
+export function toXY<T>(value: T | readonly [x: T, y: T]): XY<T> {
+  return isPair(value) ? [value[0], value[1]] : [value, value]
+}