siftlode/frontend/src/lib/keymap.sequence.test.ts

// @vitest-environment jsdom
//
// Two-step sequences (`g h`) and the page-level quiet rule, in their own file: the pending first step
// is module state, and a test that left one pending would turn the NEXT test's first key into its
// second step. Every test here starts a fake clock far past the previous test's, so nothing carries.
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { SHORTCUTS, dispatch, formatChord, helpLines, type ShortcutId } from "./keymap";
import { pushLayer, removeLayer } from "./layerStack";

let clock = Date.UTC(2030, 0, 1);
beforeEach(() => {
  vi.useFakeTimers({ toFake: ["Date"] });
  clock += 3_600_000;
  vi.setSystemTime(clock);
});
afterEach(() => vi.useRealTimers());

function press(init: KeyboardEventInit, on?: HTMLElement): KeyboardEvent {
  const e = new KeyboardEvent("keydown", { bubbles: true, cancelable: true, ...init });
  (on ?? document.body).dispatchEvent(e);
  return e;
}

/** Every page row's handler, recording which one ran. */
function pageHandlers(calls: string[]) {
  return Object.fromEntries(
    SHORTCUTS.filter((s) => s.scope === "page").map((s) => [s.id, () => void calls.push(s.id)]),
  ) as { readonly [K in ShortcutId<"page">]: () => void };
}
const listHandlers = (calls: string[]) =>
  ({
    next: () => calls.push("next"),
    prev: () => calls.push("prev"),
    left: () => {},
    right: () => {},
    up: () => {},
    down: () => {},
    open: () => {},
  }) as const;

describe("two-step sequences", () => {
  it("runs the row once both steps arrive, and not on the first alone", () => {
    const calls: string[] = [];
    expect(dispatch(press({ key: "g" }), "page", pageHandlers(calls))).toBe(true);
    expect(calls).toEqual([]);
    expect(dispatch(press({ key: "f" }), "page", pageHandlers(calls))).toBe(true);
    expect(calls).toEqual(["goFeed"]);
  });

  // Every scope has its own window listener, so the `h` completing `g h` reaches the global one too.
  it("keeps the completing key from every other scope, whichever listener runs first", () => {
    const calls: string[] = [];
    const global = {
      help: () => calls.push("help"),
      palette: () => {},
      home: () => {},
    };
    // another scope BEFORE the owner: the pending step belongs to `page`, so it stands aside
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    const h = press({ key: "h" });
    expect(dispatch(h, "global", global)).toBe(false);
    expect(dispatch(h, "page", pageHandlers(calls))).toBe(true);
    expect(calls).toEqual(["goHome"]);

    // another scope AFTER the owner: the owner stamped the event
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    const j = press({ key: "j" }); // breaks the sequence: no `g j`
    expect(dispatch(j, "page", pageHandlers(calls))).toBe(false);
    expect(dispatch(j, "list", listHandlers(calls))).toBe(false);
    expect(calls).toEqual(["goHome"]);
  });

  it("gives up after the window, so a late key is an ordinary key again", () => {
    const calls: string[] = [];
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    vi.setSystemTime(clock + 1_600);
    expect(dispatch(press({ key: "j" }), "list", listHandlers(calls))).toBe(true);
    expect(dispatch(press({ key: "f" }), "page", pageHandlers(calls))).toBe(false);
    expect(calls).toEqual(["next"]);
  });

  it("is not broken by reaching for a modifier between the steps", () => {
    const calls: string[] = [];
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    dispatch(press({ key: "Shift", shiftKey: true }), "page", pageHandlers(calls));
    dispatch(press({ key: "d" }), "page", pageHandlers(calls));
    expect(calls).toEqual(["goDownloads"]);
  });

  it("does not start or finish inside a text field", () => {
    const calls: string[] = [];
    const input = document.createElement("input");
    document.body.append(input);
    expect(dispatch(press({ key: "g" }, input), "page", pageHandlers(calls))).toBe(false);
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    expect(dispatch(press({ key: "f" }, input), "page", pageHandlers(calls))).toBe(false);
    expect(calls).toEqual([]);
    input.remove();
  });
});

describe("page-level scopes under a layer", () => {
  it("are quiet while a keyboard-owning layer is open", () => {
    const calls: string[] = [];
    const id = pushLayer();
    expect(dispatch(press({ key: "j" }), "list", listHandlers(calls))).toBe(false);
    expect(dispatch(press({ key: "s" }), "search", { focus: () => calls.push("s") })).toBe(false);
    dispatch(press({ key: "g" }), "page", pageHandlers(calls));
    dispatch(press({ key: "f" }), "page", pageHandlers(calls));
    removeLayer(id);
    expect(calls).toEqual([]);
  });

  // The layer's OWN keys must keep working — that is the player the page keys are standing aside for.
  it("leave the layer's own scope alone", () => {
    const calls: string[] = [];
    const id = pushLayer();
    expect(
      dispatch(press({ key: "k" }), "plexPlayer", { playPause: () => calls.push("pp") } as never),
    ).toBe(true);
    removeLayer(id);
    expect(calls).toEqual(["pp"]);
  });

  it("keep working under a passive layer (an open tooltip)", () => {
    const calls: string[] = [];
    const id = pushLayer({ passive: true });
    expect(dispatch(press({ key: "j" }), "list", listHandlers(calls))).toBe(true);
    removeLayer(id);
    expect(calls).toEqual(["next"]);
  });
});

describe("the page-level rows", () => {
  // Owner rule D1, enforced rather than commented: on the Hungarian layout the owner types on, a
  // chord with a modifier (or `/`, `?`, which ARE Shift chords there) is not a quick key.
  it("need no modifier and no Shift-only character", () => {
    for (const s of SHORTCUTS) {
      if (!["page", "search", "list"].includes(s.scope)) continue;
      for (const chord of s.keys) {
        for (const step of chord.split(" ")) {
          expect(step.includes("+"), `${s.scope}:${s.id} ${chord}`).toBe(false);
          expect(/^[a-z0-9,.-]$|^(Enter|Escape|Arrow(Up|Down|Left|Right))$/.test(step), chord).toBe(
            true,
          );
        }
      }
    }
  });

  it("render as the keys to press, step by step", () => {
    expect(formatChord("g h")).toBe("G H");
    expect(formatChord("g ,")).toBe("G ,");
  });

  // `g h` shares Home's line with Shift+W; leaving out an unreachable chord must not take that with it.
  it("drop an unreachable module's chord but keep the line it shares", () => {
    const lines = helpLines(["page", "global"], ["home", "feed"]);
    expect(lines.find((l) => l.labelKey === "keys.home")?.chords).toEqual(["g h", "Shift+w"]);
    expect(lines.some((l) => l.labelKey === "keys.goFeed")).toBe(true);
    expect(lines.some((l) => l.labelKey === "keys.goPlex")).toBe(false);
    expect(
      helpLines(["page", "global"], []).find((l) => l.labelKey === "keys.home")?.chords,
    ).toEqual(["Shift+w"]);
  });
});