// 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; } 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(".sheet-ribbon-tabs [data-kt]")); } if (depth === "gallery") { const panel = openPanel(container); return panel ? collect(panel.querySelectorAll("[data-kt]")) : []; } return collect(container.querySelectorAll(".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(".sheet-ribbon-pop") // ⭐⭐ W53-T07 (instruction 25) — THE OPEN POPOVER IS A CHILD OF `` 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(".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(".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("button:not(:disabled)")); } function collect(list: NodeListOf): 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("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(INITIAL); const [, bump] = useReducer((n: number) => n + 1, 0); const overlayRef = useRef(null); const previousFocusRef = useRef(null); const altDownAtRef = useRef(null); const altChordRef = useRef(false); const pendingExactRef = useRef(null); const clearPendingExact = useCallback(() => { if (pendingExactRef.current !== null) window.clearTimeout(pendingExactRef.current); pendingExactRef.current = null; }, []); useEffect(() => clearPendingExact, [clearPendingExact]); const setKt = useCallback((patch: Partial) => { 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('[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('[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( '[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('[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(".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 ( ); }