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,
  setScopeCoveredProbe,
  useGlobalKeymap,
  useHelpConditions,
  useKeyScope,
  type KeyScope,
} from "../../lib/keymap";
import { pushLayer, removeLayer } from "../../lib/layerStack";
import { useMediaKeys } from "../../lib/mediaKeys";
import { useRef, useState } from "react";
import { navItemAttrs, useListNav } from "../../lib/listNav";

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 — 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: 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");
  });

  // The player's related videos are a list inside the layer: their keys work there (`inTopLayer`), so
  // the sheet opened over the player lists them — and over a layer with no list, still does not.
  it("lists the list and menu keys over a layer that holds a list of its own", () => {
    function LayerList() {
      const ref = useRef<HTMLDivElement>(null);
      useListNav(ref, { enabled: true });
      useContextMenu<string>();
      return (
        <div data-testid="layer">
          <div ref={ref}>
            <div {...navItemAttrs(0)}>row</div>
          </div>
        </div>
      );
    }
    render(
      <Host>
        <LayerList />
      </Host>,
    );
    const withList = pushLayer({ root: () => screen.getByTestId("layer") });
    pressH();
    expect(descriptions()).toContain("keys.listStep");
    expect(descriptions()).toContain("keys.contextMenu");
    act(() => closeKeyboardHelp());
    removeLayer(withList);

    const bare = pushLayer();
    pressH();
    removeLayer(bare);
    expect(descriptions()).not.toContain("keys.listStep");
    expect(descriptions()).not.toContain("keys.contextMenu");
  });

  // The YouTube player's keys wait while a layer sits above it (its related drawer, a dialog): a
  // sheet opened there leaves them out, and one opened over the player itself lists them.
  it("leaves out a surface's keys while a layer above it has them waiting", () => {
    let covered = true;
    setScopeCoveredProbe("ytPlayer", () => covered);
    try {
      render(
        <Host>
          <Surface scope="ytPlayer" />
        </Host>,
      );
      const id = pushLayer();
      pressH();
      removeLayer(id);
      expect(descriptions()).not.toContain("keys.playPause");
      expect(descriptions()).toContain("keys.help");
      act(() => closeKeyboardHelp());
      covered = false;
      pressH();
      expect(descriptions()).toContain("keys.playPause");
    } catch (e) {
      setScopeCoveredProbe("ytPlayer", null);
      throw e;
    }
    setScopeCoveredProbe("ytPlayer", null);
  });

  // 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");
  });

  // The library player's F fills the screen with a video; an audio file has no picture, so the
  // sheet over an audio file does not offer it. Through the real hook, which publishes the answer.
  it("offers Fullscreen over a video and not over an audio file", () => {
    function Player({ tag }: { tag: "video" | "audio" }) {
      const [media, setMedia] = useState<HTMLMediaElement | null>(null);
      useMediaKeys(media);
      return tag === "video" ? <video ref={setMedia} /> : <audio ref={setMedia} />;
    }
    const { unmount } = render(
      <Host>
        <Player tag="audio" />
      </Host>,
    );
    pressH();
    expect(descriptions()).toContain("keys.playPause");
    expect(descriptions()).not.toContain("keys.fullscreen");
    unmount();
    closeKeyboardHelp();

    render(
      <Host>
        <Player tag="video" />
      </Host>,
    );
    pressH();
    expect(descriptions()).toContain("keys.fullscreen");
  });
});