Editing values

/**
 * The editing behaviour every typed field shares, whatever its value type:
 *
 * - What is typed is kept as typed until it is committed — by Enter, or by
 *   leaving the field — so nothing reformats or complains mid-keystroke.
 * - A commit reads the text through the type. A value is constrained and shown
 *   in the type's format; text that is not a value stays, marked invalid.
 * - Escape abandons the edit and shows the last value again. With nothing to
 *   abandon, Escape is left for whatever contains the field.
 * - Arrow keys step the value: Shift for a large step, Alt for a small one. In
 *   a value shown in parts — a date's day, month and year — they step the part
 *   the caret is in, and leave that part selected; the arrows to either side
 *   then move from part to part.
 * - While an input method is composing, keys belong to it: Enter confirms the
 *   composition rather than committing the field.
 * - A field that cannot be changed — read-only, or disabled — is not stepped.
 * - Leaving for another window is not leaving the field: what was being typed
 *   is still being typed on return.
 * - A change is told apart from its end. Every value on the way is a change; a
 *   gesture — a commit of what was typed, an arrow held down, a drag — is over
 *   once, and is heard then only if it left the value other than it found it.
 */
import { useCallback, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
import type { ChangeEvent, FocusEvent, KeyboardEvent, PointerEvent } from "react";
import { flushSync } from "react-dom";
import { useControllableState } from "./use-controllable-state.ts";

export type ParseResult<T> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly reason: string };

export interface Step {
  readonly direction: 1 | -1;
  /** Arrow keys are `normal`; Shift makes them `large`, Alt `small`; Page keys are `page`. */
  readonly size: "small" | "normal" | "large" | "page";
  /** The part the caret is in, for a value shown in parts. */
  readonly part?: string | undefined;
  /** How many such steps at once, as a drag makes them; one when not given. */
  readonly count?: number | undefined;
}

export interface Part {
  /** `literal` for the text between parts; otherwise the type's name for the part. */
  readonly type: string;
  readonly text: string;
}

export interface FieldType<T> {
  readonly parse: (text: string) => ParseResult<T>;
  readonly format: (value: T) => string;
  /** The formatted value in its parts, which join to what `format` returns. */
  readonly parts?: (value: T) => readonly Part[];
  /** Rounding, clamping: what a parsed value becomes before it is kept. */
  readonly constrain?: (value: T) => T;
  /** The value after a step; absent for a type that does not step. */
  readonly step?: (value: T, step: Step) => T;
  /** Where stepping starts when the field is empty. */
  readonly origin?: T;
}

export interface FieldOptions<T> {
  readonly type: FieldType<T>;
  readonly value?: T | null | undefined;
  readonly defaultValue?: T | null | undefined;
  readonly onValueChange?: ((value: T | null) => void) | undefined;
  /**
   * Hears the value a gesture ended on, once, when that is not the value it
   * began on: a commit of what was typed; the release of a key that stepped,
   * however long it was held; the `end` of what `step` began.
   */
  readonly onValueCommit?: ((value: T | null) => void) | undefined;
  /** Whether an empty field is invalid rather than a null value. */
  readonly required?: boolean | undefined;
  /**
   * Whether the text has lines. Enter then makes a new line, and the command
   * key with Enter commits.
   */
  readonly multiline?: boolean | undefined;
  /** Hears the reason text could not be read as a value, and `null` once it can. */
  readonly onInvalidChange?: ((reason: string | null) => void) | undefined;
  /**
   * Whether a press that brings focus selects the whole text, so that typing
   * replaces a value shown with its unit — as Tab does in any field.
   */
  readonly selectOnFocus?: boolean | undefined;
}

/** A field's element: a line of text, or several. */
export type FieldElement = HTMLInputElement | HTMLTextAreaElement;

export interface Field<T> {
  readonly value: T | null;
  readonly text: string;
  /** Why the text is not a value, after a commit that failed. */
  readonly invalid: string | null;
  /** Whether text is being typed that has yet to be committed. */
  readonly editing: boolean;
  /** Whether the last commit kept a different value from the one typed: one held within a range. */
  readonly constrained: boolean;
  /** Read what is typed, now. Returns whether it was a value, or there was nothing to read. */
  readonly commit: () => boolean;
  /**
   * Put a value in the field that was not typed — a day chosen from a calendar.
   * It takes the place of whatever was typed, read or not, and is one change.
   */
  readonly set: (value: T | null) => void;
  /**
   * Step as an arrow key does, from outside the field — a drag, a button held
   * down. The first begins a gesture, which `end` or `cancel` finishes. All
   * three are the same functions for the life of the field.
   */
  readonly step: (step: Step) => void;
  /** The gesture is over: `onValueCommit` hears where it ended, if it moved the value. */
  readonly end: () => void;
  /** The gesture is taken back: the value is what it was when the gesture began, and nothing is committed. */
  readonly cancel: () => void;
  readonly inputProps: {
    readonly ref: (node: FieldElement | null) => void;
    readonly value: string;
    readonly "aria-invalid": true | undefined;
    readonly "data-constrained": "" | undefined;
    readonly onChange: (event: ChangeEvent<FieldElement>) => void;
    readonly onKeyDown: (event: KeyboardEvent<FieldElement>) => void;
    readonly onKeyUp: (event: KeyboardEvent<FieldElement>) => void;
    readonly onFocus: (event: FocusEvent<FieldElement>) => void;
    readonly onPointerUp: (event: PointerEvent<FieldElement>) => void;
    readonly onBlur: (event: FocusEvent<FieldElement>) => void;
  };
}

/** The step a key asks for, or null. */
function stepFor(event: KeyboardEvent): Pick<Step, "direction" | "size"> | null {
  // With the command key, the arrows are the text's own: to its start and end.
  if (event.metaKey || event.ctrlKey) return null;
  const size = event.shiftKey ? "large" : event.altKey ? "small" : "normal";
  switch (event.key) {
    case "ArrowUp":
      return { direction: 1, size };
    case "ArrowDown":
      return { direction: -1, size };
    case "PageUp":
      return { direction: 1, size: "page" };
    case "PageDown":
      return { direction: -1, size: "page" };
    default:
      return null;
  }
}

const STEPPING: ReadonlySet<string> = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown"]);

type Range = readonly [start: number, end: number];

/** Where each part that is not a literal lies in the text the parts join to. */
function rangesOf(parts: readonly Part[]): Array<{ type: string; range: Range }> {
  const ranges: Array<{ type: string; range: Range }> = [];
  let offset = 0;
  for (const part of parts) {
    if (part.type !== "literal") ranges.push({ type: part.type, range: [offset, offset + part.text.length] });
    offset += part.text.length;
  }
  return ranges;
}

/**
 * The part a selection lies within, if it lies within one. A caret at the very
 * end of the text is in none: it is where a press beside the text puts it, not
 * a choice of the last part.
 */
function partAt(parts: readonly Part[], start: number, end: number, length: number): string | undefined {
  if (start === end && start === length) return undefined;
  return rangesOf(parts).find(({ range }) => range[0] <= start && end <= range[1])?.type;
}

export function useField<T>({
  type,
  value: valueProp,
  defaultValue = null,
  onValueChange,
  onValueCommit,
  required = false,
  multiline = false,
  onInvalidChange,
  selectOnFocus = false,
}: FieldOptions<T>): Field<T> {
  const [value, setValue] = useControllableState<T | null>(valueProp, defaultValue, onValueChange);
  // What is being typed, or null when the field shows its value.
  const [draft, setDraft] = useState<string | null>(null);
  const [invalid, setInvalid] = useState<string | null>(null);
  const [constrained, setConstrained] = useState(false);
  const text = draft ?? (value === null ? "" : type.format(value));
  const input = useRef<FieldElement>(null);
  // The part to select once the stepped value is shown.
  const stepped = useRef<string>(undefined);
  const [steps, countStep] = useReducer((count: number) => count + 1, 0);
  // Whether focus has just arrived, and by a press: its release may select the text.
  const arriving = useRef(false);
  // The value a gesture in flight began on.
  const gesture = useRef<{ readonly from: T | null }>(null);

  useLayoutEffect(() => {
    const part = stepped.current;
    stepped.current = undefined;
    if (part === undefined || value === null || type.parts === undefined) return;
    const found = rangesOf(type.parts(value)).find((candidate) => candidate.type === part);
    if (found !== undefined) input.current?.setSelectionRange(found.range[0], found.range[1]);
    // `steps` is not read: a step that leaves the value where it was is still a step.
    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [steps, value, type]);

  const ref = useCallback((node: FieldElement | null) => {
    input.current = node;
  }, []);

  const mark = useCallback(
    (reason: string | null) => {
      setInvalid(reason);
      if (reason !== invalid) onInvalidChange?.(reason);
    },
    [invalid, onInvalidChange],
  );

  const keep = useCallback(
    (next: T | null, typed = false): T | null => {
      const kept = next === null || type.constrain === undefined ? next : type.constrain(next);
      setValue(kept);
      setDraft(null);
      mark(null);
      // Told apart by how they are shown, so that rounding to the precision is not counted.
      setConstrained(typed && next !== null && kept !== null && type.format(kept) !== type.format(next));
      return kept;
    },
    [type, setValue, mark],
  );

  // What was typed is a gesture that ends as it is read.
  const settle = useCallback(
    (kept: T | null) => {
      if (!Object.is(kept, value)) onValueCommit?.(kept);
    },
    [value, onValueCommit],
  );

  const read = useCallback(
    (typed: string): boolean => {
      // Text that is the value as shown is the value: reading it again could only lose precision.
      if (value !== null && typed === type.format(value)) {
        setDraft(null);
        mark(null);
        return true;
      }
      const result = type.parse(typed);
      if (result.ok) settle(keep(result.value, true));
      else if (result.reason === "empty" && !required) settle(keep(null));
      else {
        setDraft(typed);
        mark(result.reason);
        return false;
      }
      return true;
    },
    [value, type, keep, settle, required, mark],
  );

  const commit = useCallback(() => (draft === null ? true : read(draft)), [draft, read]);

  /** One step, from what is typed when it reads as a value; `selection` is where the caret is, to name a part. */
  const stepBy = (step: Step, selection?: readonly [start: number | null, end: number | null]): void => {
    if (type.step === undefined) return;
    const typed = draft === null ? null : type.parse(draft);
    const from = typed?.ok ? typed.value : value;
    gesture.current ??= { from: value };
    countStep();
    if (from === null) {
      // An empty field's first step is to where stepping starts.
      if (type.origin !== undefined) keep(type.origin);
      return;
    }
    // The caret names a part only while the text is the value as formatted.
    stepped.current =
      selection !== undefined &&
      type.parts !== undefined &&
      text === type.format(from) &&
      selection[0] !== null &&
      selection[1] !== null
        ? partAt(type.parts(from), selection[0], selection[1], text.length)
        : undefined;
    keep(type.step(from, { ...step, part: stepped.current ?? step.part }));
  };

  const end = (): void => {
    const began = gesture.current;
    if (began === null) return;
    gesture.current = null;
    if (!Object.is(value, began.from)) onValueCommit?.(value);
  };

  const cancel = (): void => {
    const began = gesture.current;
    if (began === null) return;
    gesture.current = null;
    setValue(began.from);
    setDraft(null);
    mark(null);
    setConstrained(false);
  };

  // What is called from outside — in a drag, from a timer — acts on the field as
  // it is now, whichever render the caller last saw.
  const now = useRef({ stepBy, end, cancel });
  useLayoutEffect(() => {
    now.current = { stepBy, end, cancel };
  });
  const stepOutside = useCallback((step: Step) => {
    const node = input.current;
    if (node !== null && (node.readOnly || node.disabled)) return;
    // Shown at once: the next step of a drag starts from this one, not from what was last drawn.
    flushSync(() => now.current.stepBy(step));
  }, []);
  const endOutside = useCallback(() => now.current.end(), []);
  const cancelOutside = useCallback(() => flushSync(() => now.current.cancel()), []);

  // A value given from outside while nothing is being typed here replaces what
  // was left unread: it is another value's field now.
  const shown = useRef(value);
  useEffect(() => {
    if (Object.is(shown.current, value)) return;
    shown.current = value;
    if (draft !== null && document.activeElement !== input.current) {
      // oxlint-disable-next-line react/set-state-in-effect -- answering a value owned outside
      setDraft(null);
      mark(null);
    }
  }, [value, draft, mark]);

  // A form that is reset shows the field as it began.
  useEffect(() => {
    const form = input.current?.form;
    if (form == null) return undefined;
    const reset = () => {
      setDraft(null);
      mark(null);
      if (valueProp === undefined) setValue(defaultValue);
    };
    form.addEventListener("reset", reset);
    return () => form.removeEventListener("reset", reset);
  }, [mark, valueProp, setValue, defaultValue]);

  return {
    value,
    text,
    invalid,
    editing: draft !== null,
    constrained,
    commit,
    set: (next) => settle(keep(next)),
    step: stepOutside,
    end: endOutside,
    cancel: cancelOutside,
    inputProps: {
      ref,
      value: text,
      "aria-invalid": invalid === null ? undefined : true,
      "data-constrained": constrained ? "" : undefined,
      onChange(event) {
        setConstrained(false);
        // Text that arrives without focus was not typed — a browser filled it in —
        // and no blur will follow to commit it.
        if (document.activeElement !== event.target) read(event.target.value);
        else setDraft(event.target.value);
      },
      onKeyDown(event) {
        // Keys pressed during a composition are the input method's.
        if (event.nativeEvent.isComposing || event.keyCode === 229) return;
        const target = event.currentTarget;

        if (event.key === "Enter") {
          if (multiline && !event.metaKey && !event.ctrlKey) return;
          // Committed now, within the press, so that a form submitted by this
          // Enter is sent the value just typed — and not submitted at all if the
          // text cannot be read. Whatever contains the field can still claim the key.
          let readable = true;
          flushSync(() => {
            readable = commit();
          });
          if (!readable) event.preventDefault();
          return;
        }
        if (event.key === "Escape") {
          if (draft === null && invalid === null) return;
          event.preventDefault();
          event.stopPropagation();
          setDraft(null);
          mark(null);
          return;
        }
        if (target.readOnly || target.disabled) return;

        const { selectionStart, selectionEnd } = target;
        const parts = value !== null && draft === null ? type.parts?.(value) : undefined;
        // With one part selected, the arrows to either side move from part to part.
        if (
          parts !== undefined &&
          (event.key === "ArrowLeft" || event.key === "ArrowRight") &&
          !event.shiftKey &&
          !event.altKey &&
          !event.metaKey &&
          !event.ctrlKey &&
          selectionStart !== selectionEnd
        ) {
          const ranges = rangesOf(parts);
          const at = ranges.findIndex(
            ({ range }) => range[0] === selectionStart && range[1] === selectionEnd,
          );
          const next = at === -1 ? undefined : ranges[at + (event.key === "ArrowRight" ? 1 : -1)];
          if (next !== undefined) {
            event.preventDefault();
            target.setSelectionRange(next.range[0], next.range[1]);
          }
          return;
        }

        const step = stepFor(event);
        if (step === null || type.step === undefined) return;
        event.preventDefault();
        stepBy(step, [selectionStart, selectionEnd]);
      },
      onKeyUp(event) {
        // A key held down has stepped many times, and is one gesture.
        if (STEPPING.has(event.key)) end();
      },
      onFocus(event) {
        // Told apart from Tab, which selects the text itself, by the press still being down.
        arriving.current = selectOnFocus && event.currentTarget.matches(":active");
      },
      onPointerUp(event) {
        if (!arriving.current) return;
        arriving.current = false;
        const target = event.currentTarget;
        // A finger places the caret; and a drag that selected something is left alone.
        if (event.pointerType !== "touch" && target.selectionStart === target.selectionEnd) target.select();
      },
      onBlur() {
        arriving.current = false;
        // The release of a key held as focus left will be heard elsewhere, if at all.
        end();
        // Another window took focus, not another control: nothing has been left.
        if (!document.hasFocus()) return;
        commit();
      },
    },
  };
}