feat(keys): j/k walk the feed, s finds the search box, g jumps to a module
A feed card cost ~10 Tab stops, so the tenth card sat ~135 Tabs from the top of the page, and the only keyboard focus ring (a 60% accent outline on the thumbnail) all but vanished on the dark glass. First slice of the E11 keyboard layer (S4a); Home, Plex and the tables follow in S4b/S4c. - `lib/listNav`: one window listener over every registered list, walked in document order. `j`/`k` step item to item (on into the next list — owner decision D4), the arrows move around a grid, Enter clicks the item's own `data-nav-open` element, so it opens exactly like a click. An item root is never a Tab stop: it gets `tabindex=-1` only while the keyboard is on it, and keeps it until the next item takes it, so the player's focus restore lands back on the card. The first `j` takes the first card you can see, not the top of the list. - `VirtualGrid` takes part with `keyboardNav` (column count + scrolling an unmounted row in); `VirtualFeed` turns it on, so the feed, the library and the channel page all have it. - Keymap: two-step sequences (`g h`) whose pending step belongs to the scope that started it; the page-level scopes (`page`, `search`, `list`) are quiet while a layer that owns the keyboard is open, enforced in `dispatch`. A test pins the owner's rule that none of them needs a modifier on the Hungarian layout. - `g h/f/c/p/x/n/m/d/s/,` jump to a module this account can reach; `s` focuses the header search box and selects the old query; Escape in it hands the keyboard back to the page (Plex's typeahead spends its first Escape on its panel). - Hover popovers are passive layers: an open tooltip still takes Escape first but no longer silences the page keys. - Focus ring (owner decision D2 = B): solid 2px accent around the whole item; the app-wide button/ link/row ring goes from 60% to solid too. The item keeps a transparent resting outline because the video card transitions `all` — without it every `j` flashed a 3px white ring (measured in Chrome). - Help sheet: the new keys, in a fixed order after the surface's own; a `g` chord only for a reachable module; opened over a player or dialog it leaves out the page-level keys and the context-menu key, which nothing can reach there (the latter pre-existing since E10). - CLAUDE.md: a canonical-patterns row for list/grid keys (`useListNav` + `navItemAttrs` + `data-nav-open`, not a private arrow-key handler).
This commit is contained in:
@@ -0,0 +1,220 @@
|
||||
// @vitest-environment jsdom
|
||||
//
|
||||
// `lib/listNav` against real DOM: `j`/`k` from item to item and across lists in reading order, the
|
||||
// arrows around a grid, Enter as a click on the item's own "open" element — and the places where the
|
||||
// keys must stay out of the way (a field, an overlay, a control inside the card).
|
||||
import { useRef } from "react";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
|
||||
import { navItemAttrs, useListNav } from "./listNav";
|
||||
import { pushLayer, removeLayer } from "./layerStack";
|
||||
|
||||
afterEach(cleanup);
|
||||
|
||||
function List({
|
||||
id,
|
||||
count,
|
||||
cols = 1,
|
||||
mounted,
|
||||
reveal,
|
||||
onOpen = () => {},
|
||||
}: {
|
||||
id: string;
|
||||
count: number;
|
||||
cols?: number;
|
||||
/** Mount only the first N items, the way a virtualized grid leaves the rest out of the DOM. */
|
||||
mounted?: number;
|
||||
reveal?: (index: number) => void;
|
||||
onOpen?: (id: string) => void;
|
||||
}) {
|
||||
const ref = useRef<HTMLDivElement>(null);
|
||||
useListNav(ref, { enabled: true, count, cols, reveal });
|
||||
return (
|
||||
<div ref={ref}>
|
||||
{Array.from({ length: mounted ?? count }, (_, i) => (
|
||||
<div key={i} {...navItemAttrs(i)} data-testid={`${id}${i}`}>
|
||||
<a
|
||||
href="#"
|
||||
data-nav-open=""
|
||||
onClick={(e) => {
|
||||
e.preventDefault();
|
||||
onOpen(`${id}${i}`);
|
||||
}}
|
||||
>
|
||||
title
|
||||
</a>
|
||||
<button data-testid={`${id}${i}-action`}>action</button>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
/** A keydown where a real one starts: on whatever holds focus, bubbling to the window listener. */
|
||||
function press(key: string): KeyboardEvent {
|
||||
const e = new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true });
|
||||
act(() => {
|
||||
(document.activeElement ?? document.body).dispatchEvent(e);
|
||||
});
|
||||
return e;
|
||||
}
|
||||
|
||||
const focused = () => (document.activeElement as HTMLElement | null)?.dataset.testid;
|
||||
|
||||
describe("useListNav", () => {
|
||||
it("lands the first j on an item, then steps one item at a time", () => {
|
||||
render(<List id="a" count={3} />);
|
||||
press("j");
|
||||
expect(focused()).toBe("a0");
|
||||
press("j");
|
||||
expect(focused()).toBe("a1");
|
||||
press("k");
|
||||
expect(focused()).toBe("a0");
|
||||
});
|
||||
|
||||
// The Tab order is the reader's, not ours: only the item the keyboard is on is focusable, and the
|
||||
// previous one gives its tabindex back.
|
||||
it("roves a single tabindex=-1 and never adds a Tab stop", () => {
|
||||
render(<List id="a" count={3} />);
|
||||
expect(screen.getByTestId("a0").hasAttribute("tabindex")).toBe(false);
|
||||
press("j");
|
||||
expect(screen.getByTestId("a0").getAttribute("tabindex")).toBe("-1");
|
||||
press("j");
|
||||
expect(screen.getByTestId("a0").hasAttribute("tabindex")).toBe(false);
|
||||
expect(screen.getByTestId("a1").getAttribute("tabindex")).toBe("-1");
|
||||
});
|
||||
|
||||
// The player (E11 S2) restores focus to whatever held it when it opened. If the item gave its
|
||||
// tabindex back on blur, that restore would silently fail and focus would fall to <body>.
|
||||
it("keeps the item focusable after focus leaves it, so a dialog can restore onto it", () => {
|
||||
render(
|
||||
<>
|
||||
<List id="a" count={2} />
|
||||
<button data-testid="outside">elsewhere</button>
|
||||
</>,
|
||||
);
|
||||
press("j");
|
||||
act(() => screen.getByTestId("outside").focus());
|
||||
act(() => screen.getByTestId("a0").focus());
|
||||
expect(focused()).toBe("a0");
|
||||
});
|
||||
|
||||
it("stops at both ends of the page instead of wrapping", () => {
|
||||
render(<List id="a" count={2} />);
|
||||
press("j");
|
||||
press("k");
|
||||
expect(focused()).toBe("a0");
|
||||
press("j");
|
||||
press("j");
|
||||
expect(focused()).toBe("a1");
|
||||
});
|
||||
|
||||
// Owner decision D4: j/k walk every collection on the page in reading order.
|
||||
it("continues into the next list, and back, in document order", () => {
|
||||
render(
|
||||
<>
|
||||
<List id="a" count={2} />
|
||||
<List id="b" count={2} />
|
||||
</>,
|
||||
);
|
||||
press("j");
|
||||
press("j");
|
||||
press("j");
|
||||
expect(focused()).toBe("b0");
|
||||
press("k");
|
||||
expect(focused()).toBe("a1");
|
||||
});
|
||||
|
||||
it("moves around a grid with the arrows, row by row", () => {
|
||||
// 3 columns, 7 items: rows [0 1 2] [3 4 5] [6]
|
||||
render(<List id="a" count={7} cols={3} />);
|
||||
press("j");
|
||||
press("ArrowRight");
|
||||
expect(focused()).toBe("a1");
|
||||
press("ArrowDown");
|
||||
expect(focused()).toBe("a4");
|
||||
press("ArrowDown"); // the row below is short: land on its last item
|
||||
expect(focused()).toBe("a6");
|
||||
press("ArrowDown"); // already on the last row
|
||||
expect(focused()).toBe("a6");
|
||||
press("ArrowUp");
|
||||
expect(focused()).toBe("a3");
|
||||
press("ArrowLeft"); // left wraps to the end of the row above — reading order
|
||||
expect(focused()).toBe("a2");
|
||||
});
|
||||
|
||||
it("works the arrows from a control inside the card too", () => {
|
||||
render(<List id="a" count={4} cols={2} />);
|
||||
act(() => screen.getByTestId("a0-action").focus());
|
||||
press("ArrowDown");
|
||||
expect(focused()).toBe("a2");
|
||||
});
|
||||
|
||||
// Outside a list an arrow scrolls the page; that native meaning must survive.
|
||||
it("leaves the arrows alone when focus is not in a list", () => {
|
||||
render(<List id="a" count={4} cols={2} />);
|
||||
expect(press("ArrowDown").defaultPrevented).toBe(false);
|
||||
expect(focused()).toBeUndefined();
|
||||
});
|
||||
|
||||
it("opens the item on Enter by clicking its own open element", () => {
|
||||
const onOpen = vi.fn();
|
||||
render(<List id="a" count={2} onOpen={onOpen} />);
|
||||
press("j");
|
||||
press("j");
|
||||
expect(press("Enter").defaultPrevented).toBe(true);
|
||||
expect(onOpen).toHaveBeenCalledWith("a1");
|
||||
});
|
||||
|
||||
it("leaves Enter to a control inside the card", () => {
|
||||
const onOpen = vi.fn();
|
||||
render(<List id="a" count={2} onOpen={onOpen} />);
|
||||
act(() => screen.getByTestId("a0-action").focus());
|
||||
expect(press("Enter").defaultPrevented).toBe(false);
|
||||
expect(onOpen).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("stays out of a text field", () => {
|
||||
render(
|
||||
<>
|
||||
<input data-testid="field" />
|
||||
<List id="a" count={2} />
|
||||
</>,
|
||||
);
|
||||
act(() => screen.getByTestId("field").focus());
|
||||
press("j");
|
||||
expect(focused()).toBe("field");
|
||||
});
|
||||
|
||||
it("is quiet under a layer that owns the keyboard, but not under a tooltip", () => {
|
||||
render(<List id="a" count={2} />);
|
||||
const modal = pushLayer();
|
||||
press("j");
|
||||
expect(focused()).toBeUndefined();
|
||||
removeLayer(modal);
|
||||
|
||||
const tooltip = pushLayer({ passive: true });
|
||||
press("j");
|
||||
expect(focused()).toBe("a0");
|
||||
removeLayer(tooltip);
|
||||
});
|
||||
|
||||
// A virtualized grid only mounts a screen of rows: the next item may not exist yet.
|
||||
it("asks the list to reveal an unmounted item, then focuses it once it renders", async () => {
|
||||
const reveal = vi.fn();
|
||||
const { rerender } = render(<List id="a" count={5} mounted={2} reveal={reveal} />);
|
||||
press("j");
|
||||
press("j");
|
||||
press("j");
|
||||
expect(reveal).toHaveBeenCalledWith(2);
|
||||
expect(focused()).toBe("a1");
|
||||
rerender(<List id="a" count={5} reveal={reveal} />);
|
||||
await waitFor(() => expect(focused()).toBe("a2"));
|
||||
});
|
||||
|
||||
it("unbinds when the last list unmounts", () => {
|
||||
const { unmount } = render(<List id="a" count={2} />);
|
||||
unmount();
|
||||
expect(press("j").defaultPrevented).toBe(false);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user