Selection

/**
 * The selection model shared by every collection that selects: lists, trees,
 * grids, canvases. It is pure — keys in, keys out — so it works the same over a
 * DOM collection or a virtualised one with a million rows.
 *
 * Besides the selected keys it tracks the *anchor* (where a range starts) and
 * the *base* (what was selected before the current range), which is what lets
 * ⌘-click then Shift-click add a range to an existing selection, and a second
 * Shift-click re-draw that range instead of adding another.
 */

import type { Extent } from "./navigation.ts";

export type SelectionMode = "single" | "multiple";

/**
 * `replace` — the file-browser convention: a click or an arrow selects one item, and
 * modifiers add to it. `toggle` — every click adds or removes, like checkboxes.
 */
export type SelectionBehavior = "replace" | "toggle";

export type SelectionIntent = "replace" | "toggle" | "extend";

export interface SelectionState {
  readonly selected: ReadonlySet<string>;
  readonly anchor: string | null;
  readonly base: ReadonlySet<string>;
}

export interface SelectionOptions {
  readonly mode: SelectionMode;
  /** The keys that can be selected, in collection order. */
  readonly order: readonly string[];
  readonly disallowEmpty?: boolean;
}

const EMPTY: ReadonlySet<string> = new Set();

export function selectionState(selected: Iterable<string> = []): SelectionState {
  return { selected: new Set(selected), anchor: null, base: EMPTY };
}

function only(key: string): SelectionState {
  return { selected: new Set([key]), anchor: key, base: EMPTY };
}

/** Apply an intent to `key`. Returns the same state when nothing changes. */
export function applyIntent(
  state: SelectionState,
  intent: SelectionIntent,
  key: string,
  { mode, order, disallowEmpty = false }: SelectionOptions,
): SelectionState {
  if (!order.includes(key)) return state;
  const has = state.selected.has(key);

  if (mode === "single" || intent === "replace") {
    if (intent === "toggle" && has) {
      return disallowEmpty ? state : { selected: EMPTY, anchor: key, base: EMPTY };
    }
    return only(key);
  }

  if (intent === "toggle") {
    if (has && disallowEmpty && state.selected.size === 1) return state;
    const selected = new Set(state.selected);
    if (has) selected.delete(key);
    else selected.add(key);
    return { selected, anchor: key, base: selected };
  }

  const from = state.anchor === null ? -1 : order.indexOf(state.anchor);
  if (from === -1) return only(key);
  const to = order.indexOf(key);
  const selected = new Set(state.base);
  for (let i = Math.min(from, to); i <= Math.max(from, to); i += 1) selected.add(order[i]!);
  return { selected, anchor: state.anchor, base: state.base };
}

export function selectAll(state: SelectionState, order: readonly string[]): SelectionState {
  return { selected: new Set(order), anchor: state.anchor, base: EMPTY };
}

/** The selected keys in collection order — the order a consumer should receive them in. */
export function inOrder(selected: ReadonlySet<string>, order: readonly string[]): string[] {
  return order.filter((key) => selected.has(key));
}

export function sameSelection(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
  return a.size === b.size && [...a].every((key) => b.has(key));
}

export interface PointerGesture {
  readonly shiftKey: boolean;
  /** The platform's command key (⌘ / Ctrl). */
  readonly commandKey: boolean;
  readonly pointerType: string;
}

/**
 * What a press on an item means. A touch has no modifier keys, so in a multiple
 * selection a tap adds or removes — otherwise there would be no way to select
 * more than one item by touch.
 */
export function pointerIntent(
  { shiftKey, commandKey, pointerType }: PointerGesture,
  mode: SelectionMode,
  behavior: SelectionBehavior,
): SelectionIntent {
  if (mode === "single") return commandKey ? "toggle" : "replace";
  if (shiftKey) return "extend";
  if (commandKey || behavior === "toggle" || pointerType !== "mouse") return "toggle";
  return "replace";
}

/**
 * Whether a tap performs an item's action rather than selecting. A finger has
 * no double click, so where selecting would change nothing the tap acts: on the
 * selected item of a single selection; and, in a multiple selection that
 * replaces, while nothing is selected — a long press begins a selection there,
 * and taps add to it until it is empty again.
 */
export function tapActs(
  selected: ReadonlySet<string>,
  key: string,
  mode: SelectionMode,
  behavior: SelectionBehavior,
): boolean {
  if (mode === "single") return selected.has(key);
  return behavior === "replace" && selected.size === 0;
}

/**
 * The index of the item at `position` along the axis the items run on — the one
 * a drag has reached. Items lie in order along it, so a search measures few of
 * them however many there are. A position between two items, or past either
 * end, is the nearest item's. `-1` when there are no items.
 */
export function itemAt(count: number, extent: (index: number) => Extent, position: number): number {
  if (count === 0) return -1;
  // The first item that ends after the position.
  let low = 0;
  let high = count;
  while (low < high) {
    const middle = (low + high) >>> 1;
    if (extent(middle).end > position) high = middle;
    else low = middle + 1;
  }
  if (low === count) return count - 1;
  if (low === 0) return 0;
  const { start } = extent(low);
  if (position >= start) return low;
  return position - extent(low - 1).end <= start - position ? low - 1 : low;
}

const AUTO_SCROLL_SLOWEST = 180;
const AUTO_SCROLL_FASTEST = 3000;
const AUTO_SCROLL_GAIN = 24;

/**
 * How fast a drag held `distance` pixels past the edge of its scrolling view
 * scrolls it, in pixels a second: at a walk just outside, faster the further
 * out, up to a limit the eye can still follow.
 */
export function autoScrollSpeed(distance: number): number {
  if (distance <= 0) return 0;
  return Math.min(AUTO_SCROLL_FASTEST, AUTO_SCROLL_SLOWEST + distance * AUTO_SCROLL_GAIN);
}