Download web/src/sheet/KeyTips.tsx from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 29.7 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/sheet/KeyTips.tsx
- Command line
-
hf download hf://spaces/fsanyoto/loopable@9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/sheet/KeyTips.tsx
-
curl -L -o KeyTips.tsx https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/sheet/KeyTips.tsx
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> | |
| ); | |
| } | |