loopable / web /src /sheet /KeyTips.tsx
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
aa1490a verified
Raw History Blame
29.7 kB
// sheet/KeyTips.tsx - Excel-style Alt key tips over the sheet ribbon (wave 52, W52-T17, owner
// instruction 20, ruling R7; AutoWiki/waves/wave52/proto/excel-behaviour-spec.md Part B,
// rules KT-1 through KT-21 and D-1/D-2/D-3/D-6/D-7).
//
// ⭐⭐ WHAT THIS COMPONENT IS. A SEPARATE keyboard-capture layer, entirely independent of
// `Ribbon.tsx`'s own roving-focus handler (`onKeyDown`, gated on `open === ""`). This layer takes
// over the keyboard the moment a bare `Alt` press-and-release toggles it on, and hands the
// keyboard back the moment it closes. It never reads or writes `Ribbon.tsx`'s React state; it
// walks the DOM under `containerRef` for `[data-kt]` targets (W52-T16's registry) and calls
// `.click()` / `.focus()` on the real buttons, which is what keeps 30+ `control()` call sites in
// `Ribbon.tsx` untouched by this ticket.
//
// ⛔ CONTRACT C5 — `document`-LEVEL, `{capture: true}`, `stopPropagation()` ON EVERY KEY CONSUMED
// WHILE ACTIVE. `SheetGrid.tsx` is never imported here and never edited by this ticket; capturing
// at `document` ahead of the grid's own listener is what keeps the grid from ever seeing a
// keystroke this layer is currently interpreting (KT-19). When the layer is IDLE (no Alt pending,
// not active), this file swallows NOTHING — a bare keystroke reaches the grid exactly as before.
//
// ⛔ D-2/D-3 — BARE ALT, KEYDOWN-THEN-KEYUP, NOTHING ELSE PRESSED, UNDER 800ms, WINDOW FOCUSED.
// A bare press toggles the layer; held Alt plus a live first-level letter also enters its path
// (W54-T24). Other Alt chords belong to the browser/OS; Alt+F/Alt+D/Alt+Tab are never intercepted
// while idle. Once active, letters resolve the key-tip sequence in order. The pending-Alt state
// is cleared on `blur` and `visibilitychange` so an Alt-tab away and back never leaves a stray
// toggle armed.
//
// ⭐ KT-10/11/12 — TWO CASES, TOLD APART BY `data-kt-opens`, NEVER GUESSED FROM STRING LENGTH. A
// badge with no `data-kt-opens` is PREFIX-MATCHED (`FS` fires only once both `F` and `S` land;
// typing `F` alone hides every non-`F` badge and fires nothing, per KT-10). A control carrying
// `data-kt-opens="gallery"` OPENS its popover on its OWN badge, and this layer then re-derives a
// fresh badge set from whatever `.sheet-ribbon-pop` is now open (KT-11).
//
// ⚠ SCOPE, STATED HONESTLY (the ticket's own "best effort" clause for the third level). The first
// two levels show the tab strip's badges, then ONLY the chosen tab's group controls, with prefix
// match, Left/Right and Enter nav, and Escape/Alt exit. Strip actions use their own gallery/leaf
// path. Wave 55 gives Up/Down back to the grid immediately, except inside a colour gallery,
// where S67-T17 lets all four arrows walk the swatch grid (`swatchWalk`). The gallery level is
// exercised for Borders and Paste: every item carrying `data-kt` supplies its own letter.
// Every OTHER gallery (Insert, Delete, Format,
// Clear, Fill/Text colour, Font size, Number format) still gets Escape-to-close and generic
// arrow/Enter navigation among its menu items (`navFallback` below), because every one of them
// already carries `[data-kt-opens="gallery"][aria-expanded="true"]` — but their INSIDE items paint
// no letter badges yet. That gap is booked in the ticket's HANDOFF, not hidden here.
import { useCallback, useEffect, useReducer, useRef } from "react";
import type { RefObject } from "react";
import { KEY_TIP_GRID_ARROW_EVENT, isArrowKey, keyTipGridArrow, swatchGridStep } from "./shortcuts";
type Depth = "tabs" | "home" | "gallery";
interface KtState {
active: boolean;
depth: Depth;
prefix: string;
focusedIdx: number;
}
const INITIAL: KtState = { active: false, depth: "tabs", prefix: "", focusedIdx: 0 };
/** D-3's own number: a bare Alt keydown/keyup pair further apart than this is not "a press". */
const ALT_PRESS_MS = 800;
export interface KeyTipsProps {
/** The ribbon's own root node (`Ribbon.tsx`'s `rootRef`) — never a fresh ref. Threading a new
* prop through 30+ `control()` call sites is the wrong-shaped fix for a badge layer that only
* needs to READ the DOM those calls already stamp with `data-kt`. */
containerRef: RefObject<HTMLDivElement | null>;
}
type KeyTipElement = HTMLButtonElement | HTMLInputElement | HTMLTextAreaElement;
interface Target {
el: KeyTipElement;
code: string;
}
function isTextChar(key: string): boolean {
return /^[a-zA-Z0-9]$/.test(key);
}
/** ⭐⭐ W54-T24 (instruction 11) — THE MEASURED CAUSE OF "shortcuts do not work when done fast".
* Typed slowly, a person presses Alt, RELEASES it, then types H: the keyup toggles the layer on
* and every later letter lands. Typed fast, the same person is still HOLDING Alt when H arrives,
* which is how the owner writes the sequence and how Excel itself accepts it. On that path the
* old code marked the press a chord, refused to activate, and the whole sequence died: measured
* 0 of 5 held runs against 5 of 5 sequential runs, headless Chromium, 2026-09-06.
* This predicate is what keeps the fix narrow. A held Alt plus a letter only becomes a key-tip
* activation when that letter names a live FIRST-LEVEL badge in the tab strip (tabs and actions),
* so every other Alt chord the browser owns (Alt+D, Alt+F, Alt+Left) is never touched. */
function isFirstLevelCode(container: HTMLElement | null, ch: string): boolean {
return getTargets(container, "tabs").some((t) => t.code.startsWith(ch));
}
/** How long the pressed look stays on a control the key-tip layer fired. DESIGN's interaction
* layer: 100 to 200 ms, ease-out, transform and opacity ONLY. */
const PRESS_MS = 120;
/** ⭐ W54-T24, the second half of instruction 11. A key-tip activation calls `.click()` on a real
* button, so NO pointer event is ever dispatched and a `:active` or `pointerdown` rule on the
* ribbon can never fire for it. The key-tip path therefore needs its own brief press state, and
* this is it: a transform, which cannot move anything around it, degrading to a short opacity
* change when the reader asks for reduced motion. */
function pressFeedback(el: HTMLElement): void {
const reduced = typeof window.matchMedia === "function"
&& window.matchMedia("(prefers-reduced-motion: reduce)").matches;
const priorTransform = el.style.transform;
const priorOpacity = el.style.opacity;
const priorTransition = el.style.transition;
el.style.transition = reduced ? `opacity ${PRESS_MS}ms ease-out` : `transform ${PRESS_MS}ms ease-out`;
if (reduced) el.style.opacity = "0.72";
else el.style.transform = "scale(0.97)";
window.setTimeout(() => {
el.style.transform = priorTransform;
el.style.opacity = priorOpacity;
el.style.transition = priorTransition;
}, PRESS_MS);
}
/** Every `[data-kt]` element visible AT THIS DEPTH, with its badge code. Each depth is
* scoped to the DOM region that owns it: the tab strip, the active tab's group row, or
* the open gallery.
* ⚠ `verify_grid_ux.py::w54_t24_speed_shape` slices this file from `pressFeedback` up to
* the words "Every `[data-kt]` element", so this comment is a GATE ANCHOR: reword the rest
* of the sentence freely, never that phrase. Measured W57-T08: rewriting the whole line
* raised `ValueError: substring not found` and the gate died mid-run. */
function getTargets(container: HTMLElement | null, depth: Depth): Target[] {
if (!container) return [];
if (depth === "tabs") {
return collect(container.querySelectorAll<KeyTipElement>(".sheet-ribbon-tabs [data-kt]"));
}
if (depth === "gallery") {
const panel = openPanel(container);
return panel ? collect(panel.querySelectorAll<HTMLButtonElement>("[data-kt]")) : [];
}
return collect(container.querySelectorAll<HTMLButtonElement>(".sheet-ribbon-scroll [data-kt]"));
}
/** The open gallery panel the keyboard is inside: the ribbon popover, or, while one of its own
* flyouts is open (S67-T15's Line Color and Line Style, DOM children of the Borders panel that
* carry `sheet-ribbon-pop-portal` themselves), that innermost flyout. */
function openPanel(container: HTMLElement): HTMLElement | null {
const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
// ⭐⭐ W53-T07 (instruction 25) — THE OPEN POPOVER IS A CHILD OF `<body>` NOW. Every
// ribbon menu renders through `AnchoredOverlay`, which portals, so it is no longer a
// descendant of `Ribbon.tsx`'s `rootRef` and this container query returns null. Without
// this fallback the THIRD key-tip depth (Alt, then the group letter, then the letters
// inside the open gallery) dies silently: no error, no gate, just badges that stop
// appearing. ⚠ `document` is safe as the wider scope because exactly one popover is ever
// open - `Ribbon.tsx::open` is a single `Popover` value, not a set.
?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
if (!openPop) return null;
// S67-T17: while a flyout is open, its items are the gallery the keys walk, not the panel's.
const nested = openPop.querySelectorAll<HTMLElement>(".sheet-ribbon-pop-portal");
return nested.length ? nested[nested.length - 1] : openPop;
}
/** ⭐⭐ S67-T17 (instruction 18, O28) — THE COLOUR GALLERY'S WALK LIST, OR NULL FOR EVERY OTHER
* GALLERY. A panel is a colour gallery when it holds a `.sheet-ribbon-swatches` grid: Fill Color,
* Font Color, and the Borders gallery's Line Color flyout. Asked by CLASS, never by role, because
* Line Color's swatches are `menuitemradio` where Fill's are `menuitem`. The walk list is every
* enabled button in the panel in reading order, so the arrows reach "No fill", "Reset the text
* colour" and "Automatic" around the palette as well as the swatches in it. A gallery WITHOUT a
* swatch grid answers null and keeps W55-T05's behaviour exactly. */
function swatchWalk(container: HTMLElement | null): HTMLButtonElement[] | null {
const panel = container ? openPanel(container) : null;
if (!panel?.querySelector(".sheet-ribbon-swatches .sheet-ribbon-swatch")) return null;
return Array.from(panel.querySelectorAll<HTMLButtonElement>("button:not(:disabled)"));
}
function collect(list: NodeListOf<KeyTipElement>): Target[] {
const out: Target[] = [];
list.forEach((el) => {
const code = (el.dataset.kt || "").toUpperCase();
if (code) out.push({ el, code });
});
return out;
}
/** Every entry whose code starts with `prefix` (KT-10 -- typing the first character of a
* two-character badge hides every OTHER badge and keeps the survivors showing both chars). */
function pickTargets(container: HTMLElement | null, depth: Depth, prefix: string): Target[] {
const all = getTargets(container, depth);
return prefix ? all.filter((t) => t.code.startsWith(prefix)) : all;
}
/** A gallery that paints no `data-kt` badges yet (best-effort scope, see file header) still gets
* generic arrow/Enter navigation among its own menu items. */
function navFallback(container: HTMLElement | null, depth: Depth): HTMLButtonElement[] {
if (!container || depth !== "gallery") return [];
const panel = openPanel(container);
return panel ? Array.from(panel.querySelectorAll<HTMLButtonElement>("button:not(:disabled)")) : [];
}
function navElements(container: HTMLElement | null, depth: Depth, prefix: string): KeyTipElement[] {
const picked = pickTargets(container, depth, prefix).map((t) => t.el);
return picked.length ? picked : navFallback(container, depth);
}
export default function KeyTips({ containerRef }: KeyTipsProps) {
const stateRef = useRef<KtState>(INITIAL);
const [, bump] = useReducer((n: number) => n + 1, 0);
const overlayRef = useRef<HTMLDivElement | null>(null);
const previousFocusRef = useRef<HTMLElement | null>(null);
const altDownAtRef = useRef<number | null>(null);
const altChordRef = useRef(false);
const pendingExactRef = useRef<number | null>(null);
const clearPendingExact = useCallback(() => {
if (pendingExactRef.current !== null) window.clearTimeout(pendingExactRef.current);
pendingExactRef.current = null;
}, []);
useEffect(() => clearPendingExact, [clearPendingExact]);
const setKt = useCallback((patch: Partial<KtState>) => {
clearPendingExact();
stateRef.current = { ...stateRef.current, ...patch };
bump();
}, [bump, clearPendingExact]);
/** KT-17's soft signal for an unmatched keystroke: a brief pulse, never a state change, so it
* never disturbs a still-open two-character prefix. */
const flash = useCallback(() => {
const el = overlayRef.current;
if (!el) return;
el.classList.remove("sheet-kt-flash");
void el.offsetWidth; // force a reflow so a REPEATED miss still replays the animation
el.classList.add("sheet-kt-flash");
}, []);
const deactivateAll = useCallback((restoreFocus = true) => {
const el = previousFocusRef.current;
previousFocusRef.current = null;
setKt(INITIAL);
if (restoreFocus) requestAnimationFrame(() => el?.focus?.());
}, [setKt]);
const activateFirstLevel = useCallback(() => {
previousFocusRef.current = (document.activeElement as HTMLElement) ?? null;
setKt({ active: true, depth: "tabs", prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => {
if (!stateRef.current.active || stateRef.current.depth !== "tabs") return;
containerRef.current?.querySelector<HTMLButtonElement>('[data-ribbon="tab-home"]')?.focus();
});
}, [setKt, containerRef]);
/** S67-T17: close a flyout open inside the gallery (Line Color, Line Style) through the opener
* that toggles it, and hand focus back to that opener. False when no flyout is open. */
const flyoutOpener = useCallback((): HTMLButtonElement | null => {
const panel = containerRef.current ? openPanel(containerRef.current) : null;
if (!panel || panel.classList.contains("sheet-ribbon-pop")) return null;
return panel.parentElement?.closest(".sheet-ribbon-pop")
?.querySelector<HTMLButtonElement>('[aria-haspopup="menu"][aria-expanded="true"]') ?? null;
}, [containerRef]);
const closeFlyout = useCallback((): boolean => {
const opener = flyoutOpener();
if (!opener) return false;
opener.click();
setKt({ prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => opener.focus());
return true;
}, [flyoutOpener, setKt]);
/** KT-14/15/16's ladder: one step back per Escape, never a full exit until the first level. */
const stepBack = useCallback(() => {
const st = stateRef.current;
// S67-T17: a flyout inside the gallery is its own rung, and on ESCAPE the shared overlay
// arbiter (`ui/useEscapeClose`) is the one that closes it: the flyout is the topmost layer and
// the arbiter hears this same keydown. Closing it here as well (clicking its opener) unmounts it
// synchronously, which promotes the gallery to topmost before the arbiter runs, so the arbiter
// then closed the GALLERY too and left its 19 badges over the grid (measured on the snapshot:
// both panels gone inside the same keydown). So key tips only re-anchor on the gallery.
const opener = st.depth === "gallery" ? flyoutOpener() : null;
if (opener) {
setKt({ prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => opener.focus());
return;
}
if (st.depth === "gallery") {
const opener = containerRef.current?.querySelector<HTMLButtonElement>(
'[data-kt-opens="gallery"][aria-expanded="true"]',
);
// Galleries can open from either level, so the opener's DOM location determines where Escape returns.
const depth = opener?.closest(".sheet-ribbon-tabs") ? "tabs" : "home";
opener?.click();
setKt({ depth, prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => opener?.focus());
return;
}
if (st.depth === "home") {
if (st.prefix !== "") {
setKt({ prefix: "", focusedIdx: 0 });
return;
}
setKt({ depth: "tabs", focusedIdx: 0 });
requestAnimationFrame(() => {
containerRef.current?.querySelector<HTMLButtonElement>('[data-ribbon="tab-home"]')?.focus();
});
return;
}
deactivateAll();
}, [containerRef, deactivateAll, flyoutOpener, setKt]);
/** A first-level tab reveals its own group controls (KT-8/KT-9); strip actions follow the
* same gallery/leaf handling as group controls.
*/
const activate = useCallback((el: KeyTipElement) => {
const st = stateRef.current;
pressFeedback(el); // W54-T24: the pressed look lands on the same tick as the command
// S66-T09 (R24): a text field badge (the ribbon search, `data-kt="Q"`) ends the key-tip session
// and takes the caret. `.click()` alone never focuses an input, so it is focused first; the
// click still runs because it is the search's own open door after Escape closed its list.
if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
deactivateAll(false);
el.focus();
el.select();
// A search already focused still needs its click door after Escape dismissed the list.
el.click();
return;
}
if (st.depth === "tabs" && el.dataset.ribbon?.startsWith("tab-")) {
el.click();
setKt({ depth: "home", prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => {
navElements(containerRef.current, "home", "")[0]?.focus();
// Re-read badge targets after React replaces the active tab's group row.
bump();
});
return;
}
if (el.dataset.ktOpens === "gallery") {
el.click();
setKt({ depth: "gallery", prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => {
if (!stateRef.current.active || stateRef.current.depth !== "gallery") return;
navElements(containerRef.current, "gallery", "")[0]?.focus();
// S68-T28: re-read the portalled gallery after its items mount. The existing fixed
// badge layer paints Paste and Borders identically without changing menu layout.
bump();
});
return;
}
// ⭐ S67-T17 (O28): an item inside the gallery that opens a flyout of its own (S67-T15's Line
// Color and Line Style). Line Color is a colour gallery, so the key tips stay on and the
// arrows walk its swatches. Two frames: the flyout mounts in the first and its own overlay
// layer focuses its first item there, so the swatch focus has to land after that. A flyout
// with no swatch grid (Line Style) ends the key tips exactly as a leaf always did, leaving
// focus where the flyout put it.
if (st.depth === "gallery" && el.getAttribute("aria-haspopup") === "menu") {
el.click();
setKt({ prefix: "", focusedIdx: 0 });
requestAnimationFrame(() => requestAnimationFrame(() => {
if (!stateRef.current.active || stateRef.current.depth !== "gallery") return;
const walk = swatchWalk(containerRef.current);
if (!walk) {
deactivateAll(false);
return;
}
const start = walk.findIndex((b) => b.matches(".sheet-ribbon-swatch.is-on"));
const idx = start >= 0 ? start : walk.findIndex((b) => b.matches(".sheet-ribbon-swatch"));
walk[idx]?.focus();
setKt({ focusedIdx: Math.max(idx, 0) });
}));
return;
}
// A leaf action or a gallery item: it fires, and per real Excel the whole KeyTip layer closes
// and the keyboard returns to wherever it was before Alt was first pressed.
el.click();
deactivateAll();
}, [bump, containerRef, deactivateAll, setKt]);
const handleCharacter = useCallback((ch: string) => {
const st = stateRef.current;
const targets = getTargets(containerRef.current, st.depth);
const candidate = st.prefix + ch;
const exact = targets.find((t) => t.code === candidate);
// Keep both existing codes: Home's C (Copy) used to swallow CU (Currency). Only an
// ambiguous exact match waits; the next character or any ladder transition cancels it.
if (exact && targets.some((t) => t.code !== candidate && t.code.startsWith(candidate))) {
setKt({ prefix: candidate, focusedIdx: 0 });
pendingExactRef.current = window.setTimeout(() => {
pendingExactRef.current = null;
setKt({ prefix: "" });
if (exact.el.disabled) flash();
else activate(exact.el);
}, 250);
return;
}
if (exact) {
setKt({ prefix: "" });
if (exact.el.disabled) {
flash(); // KT-18: a disabled control's key is a no-op, not a fire
return;
}
activate(exact.el);
return;
}
if (!targets.some((t) => t.code.startsWith(candidate))) {
flash(); // KT-17: unmatched, no-op, prefix (if any) stays exactly as it was
return;
}
setKt({ prefix: candidate, focusedIdx: 0 }); // KT-10: partial two-character prefix
}, [activate, containerRef, flash, setKt]);
const onDocKeyDown = useCallback((e: KeyboardEvent) => {
if (e.key === "Alt") {
altDownAtRef.current = Date.now();
altChordRef.current = false;
// ⭐⭐ W54-T24 — TAKE THE BARE ALT AWAY FROM THE BROWSER, ON THE KEYDOWN. On Windows and
// Linux desktop Chrome an unconsumed Alt press-and-release moves focus into the browser's
// own menu bar, and everything typed next goes there instead of to this layer. The old code
// only prevented the default on the KEYUP, and only on the branch that toggled, so a press
// the layer rejected still armed the menu. Consuming it here costs nothing: a bare Alt has
// no other meaning on this page, and AltGr (which Windows delivers as Control plus Alt) is
// excluded so composed characters still work.
if (!e.ctrlKey && !e.metaKey && !e.shiftKey) e.preventDefault();
return;
}
// ⭐⭐ W54-T24 — ALT HELD PLUS A FIRST LEVEL LETTER IS THE SAME COMMAND AS ALT THEN THE
// LETTER. This is the fast typist's path and the one that used to die: see
// `isFirstLevelCode` above for the measurement and for why the match is required, which is
// what keeps every browser owned Alt chord untouched.
if ((altDownAtRef.current !== null || e.altKey) && !e.ctrlKey && !e.metaKey
&& !stateRef.current.active && isTextChar(e.key)
&& isFirstLevelCode(containerRef.current, e.key.toUpperCase())) {
e.preventDefault(); e.stopPropagation();
altChordRef.current = true; // the trailing Alt keyup must not toggle the layer a second time
activateFirstLevel();
handleCharacter(e.key.toUpperCase());
return;
}
if (altDownAtRef.current !== null) altChordRef.current = true; // a real chord, not a bare press
if (!stateRef.current.active) return; // IDLE: swallow nothing (contract C5)
const st = stateRef.current;
const targets = navElements(containerRef.current, st.depth, st.prefix);
if (e.key === "Escape") {
e.preventDefault(); e.stopPropagation();
stepBack();
return;
}
// ⭐⭐ S67-T17 (instruction 18, ruling R29 / O28) — INSIDE A COLOUR GALLERY THE ARROWS WALK
// THE PALETTE. Fill Color, Font Color and the Line Color flyout are grids, so all four arrows
// move the focus ring through them in two dimensions (`swatchGridStep`) and none of them
// reaches the grid: the selection stays where it is. This NARROWS W55-T05 / R4 for swatch
// grids only; every other gallery falls through to it unchanged. Enter applies the focused
// colour through `activate`, which closes the key tips and returns focus to the grid.
const walk = st.depth === "gallery" ? swatchWalk(containerRef.current) : null;
if (walk && isArrowKey(e.key)) {
e.preventDefault(); e.stopPropagation();
const from = walk.indexOf(document.activeElement as HTMLButtonElement);
const next = swatchGridStep(walk.map((b) => b.getBoundingClientRect()), from, e.key);
// Left at the flyout's first item closes it, as the flyout's own ArrowLeft does.
if (e.key === "ArrowLeft" && from >= 0 && next === from && closeFlyout()) return;
if (next >= 0) {
setKt({ focusedIdx: next });
walk[next].focus();
}
return;
}
if (walk && (e.key === "Enter" || e.key === " ")) {
e.preventDefault(); e.stopPropagation();
const el = walk.find((b) => b === document.activeElement) ?? walk[st.focusedIdx];
if (el) activate(el);
return;
}
// W55-T05 / R4: Up and Down leave the Alt path instead of walking its badges. The original
// document-capture key cannot reach Glide because focus currently belongs to the ribbon, so
// consume it once, close synchronously, and hand one semantic arrow to this ribbon's own
// SheetGrid wrapper. That wrapper owns selection and focus; no global key listener competes
// with the shared overlay/Escape stack.
const gridArrow = keyTipGridArrow(e.key);
if (gridArrow) {
e.preventDefault(); e.stopPropagation();
deactivateAll(false);
containerRef.current?.closest<HTMLElement>(".sheet-grid-wrap")?.dispatchEvent(
new CustomEvent(KEY_TIP_GRID_ARROW_EVENT, { detail: { key: gridArrow } }),
);
return;
}
if (e.key === "ArrowRight") {
e.preventDefault(); e.stopPropagation();
if (targets.length) {
const next = (st.focusedIdx + 1) % targets.length;
setKt({ focusedIdx: next });
targets[next]?.focus();
}
return;
}
if (e.key === "ArrowLeft") {
e.preventDefault(); e.stopPropagation();
if (targets.length) {
const next = (st.focusedIdx - 1 + targets.length) % targets.length;
setKt({ focusedIdx: next });
targets[next]?.focus();
}
return;
}
if (e.key === "Enter" || e.key === " ") {
e.preventDefault(); e.stopPropagation();
const el = targets[st.focusedIdx];
if (el) {
if (el.disabled) flash();
else activate(el);
}
return;
}
if (isTextChar(e.key)) {
e.preventDefault(); e.stopPropagation();
handleCharacter(e.key.toUpperCase());
return;
}
if (e.key === "Shift" || e.key === "Control" || e.key === "Meta" || e.key === "AltGraph") {
return; // a bare modifier changes nothing and cannot reach the grid as input on its own
}
// Any other key (Tab, Backspace, function keys, punctuation, ...): KT-19 says the grid must
// not receive it as cell input while the layer is active, so it is consumed here -- but with
// no flash, since KT-17's soft signal is for an unmatched CHARACTER, not for every
// non-actionable key a person might happen to touch.
e.preventDefault(); e.stopPropagation();
}, [activate, activateFirstLevel, closeFlyout, containerRef, deactivateAll, flash,
handleCharacter, stepBack, setKt]);
const onDocKeyUp = useCallback((e: KeyboardEvent) => {
if (e.key !== "Alt") return;
const downAt = altDownAtRef.current;
const chordUsed = altChordRef.current;
altDownAtRef.current = null;
altChordRef.current = false;
if (downAt === null || chordUsed) return; // D-2: a real chord was in play, not a bare press
if (Date.now() - downAt > ALT_PRESS_MS) return; // D-3: too slow to count as one press
if (!document.hasFocus()) return; // D-3: the window lost focus mid-press
e.preventDefault();
e.stopPropagation();
if (stateRef.current.active) deactivateAll(); // KT-16: Alt at ANY depth is a full reset
else activateFirstLevel(); // KT-1/KT-2/KT-3
}, [activateFirstLevel, deactivateAll]);
const onBlur = useCallback(() => {
clearPendingExact();
altDownAtRef.current = null;
altChordRef.current = false;
}, [clearPendingExact]);
const onVisibility = useCallback(() => {
if (document.hidden) {
clearPendingExact();
altDownAtRef.current = null;
altChordRef.current = false;
}
}, [clearPendingExact]);
useEffect(() => {
document.addEventListener("keydown", onDocKeyDown, true);
document.addEventListener("keyup", onDocKeyUp, true);
window.addEventListener("blur", onBlur);
document.addEventListener("visibilitychange", onVisibility);
return () => {
document.removeEventListener("keydown", onDocKeyDown, true);
document.removeEventListener("keyup", onDocKeyUp, true);
window.removeEventListener("blur", onBlur);
document.removeEventListener("visibilitychange", onVisibility);
};
}, [onDocKeyDown, onDocKeyUp, onBlur, onVisibility]);
const st = stateRef.current;
if (!st.active) return null;
const visible = pickTargets(containerRef.current, st.depth, st.prefix);
// S68-T28: an open gallery is a PORTALLED `.cg-overlay` (`--cg-z-overlay`, 110) since wave 53,
// while the layer's own rule still sits at `--cg-z-mapchrome` (65, written for the in-place
// `.sheet-ribbon-pop`), so every gallery badge painted UNDER its menu item and no Paste or Borders
// letter was visible. Only at gallery depth does the layer rise one step above that overlay.
const galleryLift = st.depth === "gallery" ? { zIndex: "calc(var(--cg-z-overlay) + 1)" } : undefined;
return (
<div ref={overlayRef} className="sheet-kt-layer" aria-hidden="true" style={galleryLift}>
{visible.map((t) => {
const rect = t.el.getBoundingClientRect();
return (
<span
key={`${t.code}-${Math.round(rect.left)}-${Math.round(rect.top)}`}
className={"sheet-kt-badge" + (t.el.disabled ? " is-dim" : "")}
style={{ left: rect.left - 2, top: rect.bottom - 10 }}
>
{t.code}
</span>
);
})}
</div>
);
}