@tremolo-ui/dom 0.3.0 → 0.5.0

package/src/pointer/wheel.ts

@@ -0,0 +1,58 @@
+export interface WheelOptions {
+  /**
+   * Only report events while the focus is inside the element.
+   *
+   * A control that reacts to the wheel on hover alone takes the scroll away
+   * from the page, so passing over one in a long form silently changes its
+   * value. Requiring focus makes that an explicit act.
+   *
+   * The check is `contains`, not an identity test: the element that actually
+   * takes focus is usually a descendant, such as a thumb or an `<input>`, and
+   * a caller may have replaced it with markup of their own.
+   *
+   * @default false
+   */
+  requireFocus?: boolean
+}
+
+export interface WheelInstance {
+  /** Replace the given options, keeping the listener in place. */
+  update: (options: WheelOptions) => void
+  destroy: () => void
+}
+
+/**
+ * Listen to wheel events on an element.
+ *
+ * The listener is registered with `passive: false` so that the handler can call
+ * `preventDefault()` to stop the page from scrolling.
+ */
+export function createWheel(
+  element: Element,
+  onWheel: (event: WheelEvent) => void,
+  options: WheelOptions = {},
+): WheelInstance {
+  let opts = options
+
+  function hasFocus() {
+    const active = element.ownerDocument?.activeElement
+    return !!active && element.contains(active)
+  }
+
+  const handler = (event: Event) => {
+    if (opts.requireFocus && !hasFocus()) return
+    onWheel(event as WheelEvent)
+  }
+
+  element.addEventListener('wheel', handler, { passive: false })
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    destroy: () => {
+      // Only `capture` matters when removing, and it is false here.
+      element.removeEventListener('wheel', handler)
+    },
+  }
+}

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]
+}