siftlode/frontend/src/components/ui/KeyboardHelp.dom.test.tsx

// @vitest-environment jsdom
//
// Contract of the app-wide cheat sheet: `h` opens it, it lists the SCOPES that are live (innermost
// first, global last), and it hides a `when` row whose condition the surface has not published.
// i18n is key-passthrough, so the asserted text is the i18n key.
import { describe, it, expect, vi, afterEach } from "vitest";
import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
import KeyboardHelp from "./KeyboardHelp";
import { useContextMenu } from "./useContextMenu";
import {
  closeKeyboardHelp,
  useGlobalKeymap,
  useHelpConditions,
  useKeyScope,
  type KeyScope,
} from "../../lib/keymap";
import { pushLayer, removeLayer } from "../../lib/layerStack";

vi.mock("react-i18next", async (importOriginal) => {
  const actual = await importOriginal<typeof import("react-i18next")>();
  return { ...actual, useTranslation: () => ({ t: (k: string) => k }) };
});

// The open flag is module state shared by the whole app (one sheet, opened from anywhere), so a
// test that leaves it open would flip the NEXT test's toggle into a close.
afterEach(() => {
  cleanup();
  closeKeyboardHelp();
});

/** App's job: it binds the `global` scope (h / Mod+K / Shift+W) and the `page` scope (the `g` chords)
 *  once for the whole tree. Home is the one module this stand-in account reaches, so the page block
 *  is the single `G H` chord, sharing Shift+W's line. */
function Host({ children }: { children?: React.ReactNode }) {
  useGlobalKeymap(true, () => {}, ["home"]);
  return (
    <>
      {children}
      <KeyboardHelp />
    </>
  );
}

/** A stand-in for a surface that registers a scope while mounted, the way the players do. */
function Surface({ episode, scope = "plexPlayer" }: { episode?: boolean; scope?: KeyScope }) {
  useKeyScope(scope);
  useHelpConditions({ episode: !!episode });
  return null;
}

const pressH = () =>
  act(() => {
    fireEvent.keyDown(document.body, { key: "h" });
  });

const descriptions = () => screen.getAllByRole("definition").map((el) => el.textContent);

describe("KeyboardHelp", () => {
  it("opens and closes on the global h", () => {
    render(<Host />);
    expect(screen.queryByText("keys.title")).toBeNull();
    pressH();
    expect(screen.getByText("keys.title")).toBeTruthy();
    pressH();
    expect(screen.queryByText("keys.title")).toBeNull();
  });

  it("does not open while a field has focus", () => {
    render(<Host />);
    const input = document.createElement("input");
    document.body.append(input);
    act(() => {
      fireEvent.keyDown(input, { key: "h" });
    });
    expect(screen.queryByText("keys.title")).toBeNull();
    input.remove();
  });

  it("leads with the live surface and trails with the app-wide keys", () => {
    render(
      <Host>
        <Surface />
      </Host>,
    );
    pressH();
    const rows = descriptions();
    // A plexPlayer row first, the app-wide rows last — the reading order the reader wants. (Home's
    // line comes from the page block, which sits between the two; Shift+W joins it there.)
    expect(rows[0]).toBe("keys.playPause");
    expect(rows.slice(-3)).toEqual(["keys.home", "keys.palette", "keys.help"]);
  });

  it("lists only the app-wide keys when no surface is registered", () => {
    render(<Host />);
    pressH();
    expect(descriptions()).toEqual(["keys.home", "keys.palette", "keys.help"]);
  });

  // The context menu is NOT app-wide: it has its own scope, registered by `useContextMenu`, so the
  // sheet only offers Shift+F10 where something actually answers it. Advertising it globally was a
  // promise the feed, Plex, Downloads and Settings did not keep (E10 review round 1) — the test above
  // pins the other half, that a bare app lists the two global keys and nothing else.
  // Through the REAL hook, not a scope stub: round 2 showed that commenting out
  // `useKeyScope("contextMenu")` inside `useContextMenu` left the whole suite green, because the
  // only coverage registered the scope by hand. This binds the sheet to the thing that owns it.
  it("offers the context-menu key on a surface that has one, and not otherwise", () => {
    function WithMenu() {
      useContextMenu<string>();
      return null;
    }
    const { unmount } = render(
      <Host>
        <WithMenu />
      </Host>,
    );
    pressH();
    expect(descriptions()).toContain("keys.contextMenu");

    unmount();
    cleanup();
    closeKeyboardHelp();
    render(<Host />);
    pressH();
    expect(descriptions()).not.toContain("keys.contextMenu");
  });

  // Opened over a player, Shift+F10 has nothing to reach — focus is inside the player, not on a row.
  it("drops the context-menu key from a sheet opened over a keyboard-owning layer", () => {
    function WithMenu() {
      useContextMenu<string>();
      return null;
    }
    render(
      <Host>
        <WithMenu />
      </Host>,
    );
    const id = pushLayer();
    pressH();
    removeLayer(id);
    expect(descriptions()).not.toContain("keys.contextMenu");
    expect(descriptions()).toContain("keys.help");
  });

  // Two live context menus (the Playlists page mounts one, its rail another) must not double the row.
  it("lists the context-menu chords once however many surfaces register", () => {
    function WithMenu() {
      useContextMenu<string>();
      return null;
    }
    render(
      <Host>
        <WithMenu />
        <WithMenu />
      </Host>,
    );
    pressH();
    expect(descriptions().filter((d) => d === "keys.contextMenu")).toHaveLength(1);
    expect(screen.getAllByText("⇧ F10")).toHaveLength(1);
  });

  // "Previous / next episode" inside a movie would be a promise the player does not keep.
  it("hides a conditional row until its surface says it applies", () => {
    const { unmount } = render(
      <Host>
        <Surface />
      </Host>,
    );
    pressH();
    expect(descriptions()).not.toContain("keys.episode");
    unmount();
    closeKeyboardHelp(); // the sheet outlives the tree it was opened from

    render(
      <Host>
        <Surface episode />
      </Host>,
    );
    pressH();
    expect(descriptions()).toContain("keys.episode");
  });
});