Connecting

/**
 * Joining one thing to another by hand: a port to a port, a pin to a socket.
 * What may be joined is the owner's to say — `targets` gives the ports a
 * connection from one may end on — and this owns the gesture.
 *
 * - **By a drag.** A press on a port that moves becomes a line out of it. It
 *   ends on the port it is released over — or the nearest it may end on within
 *   reach, a reach that is wider for a finger than for a mouse. Released on a
 *   port it may not end on, it is refused, and says which; released on nothing,
 *   it says where. Escape takes it back.
 * - **By two presses.** A click or a tap on a port begins from it, and one on
 *   another ends there: there is no need to hold anything down. A press
 *   anywhere else gives it up.
 * - **By the keyboard.** Enter or Space on a port begins from it, and focus
 *   goes to the nearest port it may end on. The arrow keys move among those by
 *   direction, Tab and Shift-Tab through them in order; Enter ends there, and
 *   Escape gives it up and returns to where it began.
 * - **Every port says what it is to the connection** while one lasts: where it
 *   began, where it may end, where it would end now, where it is refused.
 *
 * Ports are buttons; spread `portProps(key)` on each. Something else that a
 * connection can be dragged from — the end of a line already drawn — takes
 * `gripProps(key, payload)`, and the payload comes back with the result.
 */
import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
import type {
  CSSProperties,
  FocusEvent,
  KeyboardEvent,
  MouseEvent,
  PointerEvent as ReactPointerEvent,
} from "react";
import { nearestInDirection } from "../algorithms/geometry.ts";
import type { Direction, Point, Rect } from "../algorithms/geometry.ts";
import { useDrag } from "./drag.ts";
import type { Drag } from "./drag.ts";

/** How near a port a release must be to end on it, in screen pixels. */
export const CONNECT_REACH = { mouse: 12, pen: 16, touch: 28 } as const;

/** The reach for a kind of pointer; one that is not known is given the widest. */
export function connectReach(pointerType: string): number {
  return pointerType === "mouse" || pointerType === "pen" ? CONNECT_REACH[pointerType] : CONNECT_REACH.touch;
}

/**
 * Which of some boxes a point would end on: the nearest of those `allowed`
 * that is within `reach` of it, a point inside a box being no distance from
 * it. `boxes` holds each as left, top, right, bottom; returns the box's number,
 * or -1. Of two as near, the first.
 */
export function nearestBox(
  boxes: ArrayLike<number>,
  allowed: ArrayLike<number> | null,
  x: number,
  y: number,
  reach: number,
): number {
  let best = -1;
  let nearest = Infinity;
  for (let index = 0; index * 4 < boxes.length; index += 1) {
    if (allowed !== null && !allowed[index]) continue;
    const dx = Math.max(boxes[index * 4]! - x, 0, x - boxes[index * 4 + 2]!);
    const dy = Math.max(boxes[index * 4 + 1]! - y, 0, y - boxes[index * 4 + 3]!);
    const distance = Math.hypot(dx, dy);
    if (distance <= reach && distance < nearest) {
      best = index;
      nearest = distance;
    }
  }
  return best;
}

/** A connection being made. */
export interface Connecting<P = undefined> {
  /** The port it began from. */
  readonly from: string;
  readonly payload: P | undefined;
  /** Held down and dragged, or begun and to be ended by a second press or the keyboard. */
  readonly how: "drag" | "pick";
  /** Where the pointer is, in the viewport's coordinates; `null` when there is none to follow. */
  readonly at: Point | null;
  /** The port it would end on, were it ended now. */
  readonly target: string | null;
  /** A port the pointer is on that it may not end on. */
  readonly refused: string | null;
}

export interface ConnectOptions<P = undefined> {
  readonly disabled?: boolean | undefined;
  /** The ports a connection from `from` may end on, in the order Tab goes through them. */
  readonly targets: (from: string, payload: P | undefined) => readonly string[];
  readonly onConnect: (from: string, to: string, payload: P | undefined) => void;
  /** Ended on a port it may not end on — or, `to` being `null`, begun where there is nowhere to go. */
  readonly onRefuse?: ((from: string, to: string | null, payload: P | undefined) => void) | undefined;
  /** A drag released on no port: where, in the viewport's coordinates. */
  readonly onMiss?: ((from: string, at: Point, payload: P | undefined) => void) | undefined;
  /** A connection was begun: how, and the ports it may end on. */
  readonly onBegin?:
    | ((from: string, how: "drag" | "pick", targets: readonly string[], payload: P | undefined) => void)
    | undefined;
  /**
   * Each move of a drag, with the port it would end on, and its end however it
   * ended (`null`): for moving a view along under it.
   */
  readonly onDrag?: ((drag: Drag | null, target: string | null) => void) | undefined;
}

export type PortState = "source" | "candidate" | "target" | "refused" | "unavailable";

export interface PortProps {
  readonly "data-connect": string;
  readonly "data-connect-port": string;
  readonly "data-connect-state": PortState | undefined;
  readonly style: CSSProperties;
  readonly onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
  readonly onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;
  readonly onLostPointerCapture: (event: ReactPointerEvent<HTMLElement>) => void;
  readonly onPointerEnter: (event: ReactPointerEvent<HTMLElement>) => void;
  readonly onPointerLeave: (event: ReactPointerEvent<HTMLElement>) => void;
  readonly onClick: (event: MouseEvent<HTMLElement>) => void;
  readonly onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
  readonly onFocus: (event: FocusEvent<HTMLElement>) => void;
}

export type GripProps = Pick<PortProps, "style" | "onPointerDown" | "onLostPointerCapture">;

export interface ConnectResult<P = undefined> {
  /** The connection being made, or `null`. */
  readonly connecting: Connecting<P> | null;
  /** To spread on a port: a button. */
  readonly portProps: (key: string) => PortProps;
  /** To spread on something else a connection from `key` is dragged from. */
  readonly gripProps: (key: string, payload?: P) => GripProps;
  /** Begin from a port, to be ended by the keyboard or a press: focus goes to the nearest port it may end on. */
  readonly begin: (from: string, payload?: P) => boolean;
  readonly cancel: () => void;
  /** Look again at what the pointer is over, the ports having moved under it: the port a drag would now end on. */
  readonly aimAgain: () => string | null;
}

const NONE: ReadonlySet<string> = new Set();
// A finger must not scroll the page out from under the line it is drawing.
const STYLE: CSSProperties = { touchAction: "none" };
const ARROWS: Readonly<Record<string, Direction>> = {
  ArrowLeft: "left",
  ArrowRight: "right",
  ArrowUp: "up",
  ArrowDown: "down",
};

export function useConnect<P = undefined>(options: ConnectOptions<P>): ConnectResult<P> {
  const scope = useId();
  const latest = useRef(options);
  useEffect(() => {
    latest.current = options;
  });
  const [connecting, setConnecting] = useState<Connecting<P> | null>(null);
  // As it stands now, for handlers that outlive the render they were made in.
  const now = useRef<Connecting<P> | null>(null);
  const order = useRef<readonly string[]>([]);
  const allowed = useRef<ReadonlySet<string>>(NONE);
  // The same set, for what is drawn from it.
  const [takers, setTakers] = useState<ReadonlySet<string>>(NONE);
  const pressed = useRef<{ from: string; payload: P | undefined } | null>(null);
  const pointer = useRef({ x: 0, y: 0, type: "mouse" });
  const began = useRef<HTMLElement | null>(null);
  // Whether the press now ending was a finger's, answered when it lifted.
  const lifted = useRef(false);

  const set = useCallback((next: Connecting<P> | null) => {
    now.current = next;
    setConnecting(next);
  }, []);

  const ports = useCallback(
    () => [...document.querySelectorAll<HTMLElement>(`[data-connect="${scope}"][data-connect-port]`)],
    [scope],
  );
  const portOf = useCallback(
    (key: string) => ports().find((element) => element.dataset.connectPort === key) ?? null,
    [ports],
  );

  /** What a pointer at a place would end on, and what it is on that refuses it. */
  const aim = useCallback(
    (x: number, y: number, pointerType: string, from: string) => {
      const elements = ports().filter((element) => element.dataset.connectPort !== from);
      const boxes = new Float64Array(elements.length * 4);
      const open = new Uint8Array(elements.length);
      for (const [index, element] of elements.entries()) {
        const box = element.getBoundingClientRect();
        boxes.set([box.left, box.top, box.right, box.bottom], index * 4);
        open[index] = allowed.current.has(element.dataset.connectPort!) ? 1 : 0;
      }
      const target = nearestBox(boxes, open, x, y, connectReach(pointerType));
      // Refused only by a port the pointer is on: being near one it may not end on says nothing.
      const on = target === -1 ? nearestBox(boxes, null, x, y, 0) : -1;
      return {
        target: target === -1 ? null : elements[target]!.dataset.connectPort!,
        refused: on === -1 ? null : elements[on]!.dataset.connectPort!,
      };
    },
    [ports],
  );

  const open = useCallback(
    (from: string, payload: P | undefined, how: "drag" | "pick", at: Point | null): boolean => {
      const { targets, onRefuse, onBegin } = latest.current;
      const list = targets(from, payload);
      // A drag may still begin, to show there is nowhere to go; a pick with nowhere to go is not begun.
      if (list.length === 0 && how === "pick") {
        onRefuse?.(from, null, payload);
        return false;
      }
      order.current = list;
      const taking = new Set(list);
      allowed.current = taking;
      setTakers(taking);
      set({ from, payload, how, at, target: null, refused: null });
      onBegin?.(from, how, list, payload);
      return true;
    },
    [set],
  );

  const drag = useDrag({
    onPress(press) {
      if (latest.current.disabled === true || pressed.current === null) return false;
      pointer.current = { x: press.x, y: press.y, type: press.pointerType };
      return true;
    },
    onStart(start) {
      const { from, payload } = pressed.current!;
      open(from, payload, "drag", { x: start.x, y: start.y });
    },
    onMove(move) {
      const current = now.current;
      if (current === null) return;
      pointer.current = { x: move.x, y: move.y, type: move.pointerType };
      const aimed = aim(move.x, move.y, move.pointerType, current.from);
      set({ ...current, at: { x: move.x, y: move.y }, ...aimed });
      latest.current.onDrag?.(move, aimed.target);
    },
    onEnd(end) {
      const current = now.current;
      if (current === null) return;
      const { onConnect, onRefuse, onMiss, onDrag } = latest.current;
      // Aimed once more: the release is where the pointer is now, whatever the last move found.
      const { target, refused } = aim(end.x, end.y, end.pointerType, current.from);
      set(null);
      onDrag?.(null, null);
      if (target !== null) onConnect(current.from, target, current.payload);
      else if (refused !== null) onRefuse?.(current.from, refused, current.payload);
      else onMiss?.(current.from, { x: end.x, y: end.y }, current.payload);
    },
    onCancel() {
      set(null);
      latest.current.onDrag?.(null, null);
    },
  });

  const cancel = useCallback(() => {
    const current = now.current;
    if (current === null) return;
    if (current.how === "drag") {
      drag.cancel();
      return;
    }
    set(null);
    // Focus goes back to where the connection began, if it was among the ports that it left.
    const active = document.activeElement;
    if (active instanceof HTMLElement && active.dataset.connect === scope) {
      began.current?.focus({ preventScroll: true });
    }
  }, [drag, scope, set]);

  const begin = useCallback(
    (from: string, payload?: P): boolean => {
      if (latest.current.disabled === true || !open(from, payload, "pick", null)) return false;
      const source = portOf(from);
      began.current = document.activeElement instanceof HTMLElement ? document.activeElement : source;
      // To the nearest port it may end on, from the one it began at.
      const candidates = ports().filter((element) => allowed.current.has(element.dataset.connectPort!));
      const centre = (element: HTMLElement | null) => {
        const box = element?.getBoundingClientRect();
        return box === undefined
          ? { x: 0, y: 0 }
          : { x: box.left + box.width / 2, y: box.top + box.height / 2 };
      };
      const origin = centre(source);
      let nearest: HTMLElement | null = null;
      let least = Infinity;
      for (const element of candidates) {
        const place = centre(element);
        const distance = Math.hypot(place.x - origin.x, place.y - origin.y);
        if (distance < least) {
          least = distance;
          nearest = element;
        }
      }
      nearest?.focus({ preventScroll: true });
      return true;
    },
    [open, portOf, ports],
  );

  /** End a pick on a port: join it, or be refused by it. */
  const end = useCallback(
    (current: Connecting<P>, key: string) => {
      const { onConnect, onRefuse } = latest.current;
      if (key === current.from) {
        cancel();
        return;
      }
      if (!allowed.current.has(key)) {
        // Still being made: the next press may be on a port that takes it.
        onRefuse?.(current.from, key, current.payload);
        return;
      }
      set(null);
      onConnect(current.from, key, current.payload);
    },
    [cancel, set],
  );

  // While a pick lasts, a press anywhere but on a port gives it up.
  const picking = connecting?.how === "pick";
  useEffect(() => {
    if (!picking) return undefined;
    const stop = new AbortController();
    document.addEventListener(
      "pointerdown",
      (event) => {
        const port = event.target instanceof Element ? event.target.closest("[data-connect-port]") : null;
        if (!(port instanceof HTMLElement) || port.dataset.connect !== scope) cancel();
      },
      { capture: true, signal: stop.signal },
    );
    // Wherever focus is: a pick begun by a press need not have moved it to a port.
    document.addEventListener(
      "keydown",
      (event) => {
        if (event.key !== "Escape") return;
        // Escape is the connection's own while there is one: it does not also clear what is around it.
        event.preventDefault();
        event.stopPropagation();
        cancel();
      },
      { capture: true, signal: stop.signal },
    );
    return () => stop.abort();
  }, [picking, scope, cancel]);

  const aimAgain = useCallback(() => {
    const current = now.current;
    if (current === null || current.how !== "drag") return null;
    const { x, y, type } = pointer.current;
    const aimed = aim(x, y, type, current.from);
    set({ ...current, ...aimed });
    return aimed.target;
  }, [aim, set]);

  const onLostPointerCapture = drag.props.onLostPointerCapture;
  const pressOn = drag.props.onPointerDown;

  // What the ports are to the connection: the same from one move of it to the next, until it changes.
  const from = connecting?.from;
  const target = connecting?.target;
  const refused = connecting?.refused;
  const stage = useMemo(
    () => (from === undefined ? null : { from, target, refused, allowed: takers }),
    [from, target, refused, takers],
  );

  const portProps = useCallback(
    (key: string): PortProps => {
      const state: PortState | undefined =
        stage === null
          ? undefined
          : key === stage.from
            ? "source"
            : key === stage.target
              ? "target"
              : key === stage.refused
                ? "refused"
                : stage.allowed.has(key)
                  ? "candidate"
                  : "unavailable";
      /** While a pick lasts, the port the pointer or focus is on is where it would end. */
      const point = (to: string | null) => {
        const picked = now.current;
        if (picked === null || picked.how !== "pick" || picked.target === to) return;
        if (to === null || allowed.current.has(to)) set({ ...picked, target: to });
      };
      return {
        "data-connect": scope,
        "data-connect-port": key,
        "data-connect-state": state,
        style: STYLE,
        onPointerDown(event) {
          pressed.current = { from: key, payload: undefined };
          lifted.current = false;
          pressOn(event);
        },
        // A finger let go where it was put down has pressed the port, however long it rested:
        // a browser that took the rest for a long press sends no click after it.
        onPointerUp(event) {
          if (event.pointerType === "mouse" || latest.current.disabled === true) return;
          const picked = now.current;
          if (picked?.how === "drag" || pressed.current?.from !== key) return;
          lifted.current = true;
          if (picked !== null) end(picked, key);
          else if (open(key, undefined, "pick", null)) began.current = event.currentTarget;
        },
        onLostPointerCapture,
        onPointerEnter(event) {
          if (event.pointerType === "mouse") point(key);
        },
        onPointerLeave(event) {
          if (event.pointerType === "mouse" && now.current?.target === key) point(null);
        },
        onFocus() {
          point(key);
        },
        // A button's click is also Enter's and Space's, and assistive technology's.
        onClick(event) {
          if (latest.current.disabled === true) return;
          // The click that follows a finger's lift has been answered already.
          if (lifted.current) {
            lifted.current = false;
            return;
          }
          const picked = now.current;
          if (picked !== null) {
            if (picked.how === "pick") end(picked, key);
            return;
          }
          // Pressed by a key, the way on is by keys: focus goes to where it may end.
          if (event.detail === 0) begin(key);
          else if (open(key, undefined, "pick", null)) began.current = event.currentTarget;
        },
        onKeyDown(event) {
          const picked = now.current;
          if (picked === null || picked.how !== "pick") return;
          const direction = ARROWS[event.key];
          if (event.key === "Tab") {
            // Round and round the ports it may end on: Tab does not leave until it is ended or given up.
            const list = order.current;
            const place = list.indexOf(key);
            const step = event.shiftKey ? -1 : 1;
            const next =
              place === -1
                ? list[event.shiftKey ? list.length - 1 : 0]
                : list[(place + step + list.length) % list.length];
            if (next !== undefined) portOf(next)?.focus({ preventScroll: true });
          } else if (direction !== undefined) {
            const here = event.currentTarget;
            const elements = [
              here,
              ...ports().filter(
                (element) => element !== here && allowed.current.has(element.dataset.connectPort!),
              ),
            ];
            const rects: Rect[] = elements.map((element) => {
              const box = element.getBoundingClientRect();
              return { x: box.left, y: box.top, width: box.width, height: box.height };
            });
            elements[nearestInDirection(rects, 0, direction)]?.focus({ preventScroll: true });
          } else {
            return;
          }
          // These keys are the connection's while it lasts, not whatever is around it's.
          event.preventDefault();
          event.stopPropagation();
        },
      };
    },
    [stage, scope, pressOn, onLostPointerCapture, set, end, begin, open, portOf, ports],
  );

  const gripProps = useCallback(
    (key: string, payload?: P): GripProps => ({
      style: STYLE,
      onPointerDown(event) {
        pressed.current = { from: key, payload };
        pressOn(event);
      },
      onLostPointerCapture,
    }),
    [pressOn, onLostPointerCapture],
  );

  return useMemo(
    () => ({ connecting, portProps, gripProps, begin, cancel, aimAgain }),
    [connecting, portProps, gripProps, begin, cancel, aimAgain],
  );
}