fix(useHold): suppress trailing repeats and deliver onRelease after a hold

[chiefcll]

Addresses five issues found while migrating a webOS/Tizen/Android TV app off the deprecated keyHoldOptions / userKeyHoldMap path onto useHold.

The main bug

A hold action typically moves focus while the key is still physically down — hold OK to open a context menu. Two things then go wrong, and neither can be fixed by the element that owns the hold, because once focus moves it is no longer in the focus path:

1. The platform's trailing auto-repeat key-downs propagate down the new focus path and fire whatever just took focus.
2. The key-up goes there too, so releaseHold never runs and onRelease silently never fires — contradicting the documented contract.

Both are regressions from the legacy userKeyHoldMap path, which got the same protection for free by returning early from every key-down for a hold-mapped key (focusManager.ts handleKeyEvents).

Fix

Since both are propagation concerns, the latch lives in the focus manager, which still owns propagation after focus leaves the element:

suppressKeyUntilRelease(keyOrEvent, onRelease?)
releaseKeySuppression(keyOrEvent)

• Drops auto-repeat key-downs for the key until it is released.
• The release callback is delivered wherever focus has moved — that is what fixes onRelease.
• Suppression lifts on key-up or on the next non-repeat key-down, so a swallowed key-up (webOS) cannot wedge a key permanently.
• Non-repeat key-downs are never suppressed, so a real press always gets through.

useHold registers the latch itself when its hold fires. Double-firing is avoided by ordering: the keyup branch lifts suppression before propagating, so if the element is still focused, releaseHold finds holdFired === false and no-ops.

Both helpers are exported from @solidtv/solid/primitives for hold logic written outside the primitive.

Also in this PR

holdRequiresRepeat (default true, no behavior change). Hold detection reads e.repeat, so on a platform delivering neither key-up nor auto-repeat, a genuine long press resolved as a tap and a hold gesture was unreachable — the opposite of what keyHoldOptions did, which fired the hold purely on a timer and never consulted e.repeat. Setting this to false restores that semantics. An early key-up still resolves as a tap either way.

Callback context. onHold / onEnter / onRelease were () => void, so every call site had to stash KeyHandler arguments in a closure and wrap startHold. They now receive (e?, target?, handlerElm?), matching KeyHandler's shape. onHold and timer-resolved onEnter / onRelease replay the context captured from the originating key-down, since they fire from a timer with no event of their own.

Types. The return was inferred as ((e?: KeyboardEvent) => boolean)[] — a plain array — while the JSDoc claimed a tuple. Now explicitly [HoldHandler, HoldHandler]. The docs also omitted the KeyboardEvent parameter entirely; it is now stated, with a warning that a wrapper which drops the event yields a primitive that can never detect a hold — silently, and typically only on device.

Docs: startHold stops propagation. It returns true unconditionally, which ends the bubble phase, so ancestor handlers for that key never run. This is structural, not incidental: whether the press was a tap is not known until key-up or until the timer fires, by which point the propagation pass is over, so the deferred tap cannot be handed back. Documented as a caveat with the parent-walk workaround, rather than adding a propagation-resume API.

Reviewer notes

• The suppression fix depends on startHold receiving the event (if (e) suppressKeyUntilRelease(e, fireRelease)). A wrapper that drops the event now loses hold detection and suppression together. Called out in the JSDoc and docs — happy to add a __DEV__ warn if you'd rather it fail loudly.
• releaseKeySuppression has no in-tree caller; it exists as the documented pair to suppressKeyUntilRelease for consumers.
• Default behavior is unchanged for anyone whose hold does not move focus.

Verification

• npm run tsc clean.
• npm test — 164/164 across 15 files.
• npm run lint — 0 errors, 152 warnings, identical to the pre-change baseline (the 2 warnings in focusManager.ts are pre-existing, at line 200, unrelated).
• New tests/keySuppression.test.tsx drives real keydown/keyup through useFocusManager against a focused tree: repeats dropped while latched, key-up lifting, fresh-keydown lifting when key-up never arrives, non-repeat presses never suppressed.
• tests/useHold.spec.ts — 9 added, covering holdRequiresRepeat both ways, latch registration, latch-delivered onRelease, no-double-fire, and context propagation to each callback.

Not verified on real hardware — the reporter's original repro was LG webOS with a physical remote.

🤖 Generated with Claude Code

[chiefcll]

Follow-up: holdRequiresRepeat is now three-state, defaulting to 'auto'

Reported against the first commit: webOS emits no OS-level repeat === true for the Back key, so requiring an auto-repeat to confirm a hold makes a Back hold unreachable there.

The static holdRequiresRepeat: false flag from the first commit did unblock it, but it was the wrong shape. Repeat delivery is a per-key property, not a per-platform one — on webOS, OK emits auto-repeat but swallows key-up, and Back is the exact reverse. A single boolean per useHold instance forces the app to know and hard-code that matrix.

'auto' (new default)

The discriminator is key-up delivery, which is the only thing that separates "still held" from "already released, key-up swallowed" at the threshold:

• Key delivers key-up (webOS Back) — reaching the threshold without one means it is genuinely still down. No auto-repeat needed; resolve by timer → onHold.
• Key swallows key-up (webOS OK) — a finished press is indistinguishable from one still held, so only an auto-repeat can confirm a hold. Without one → onEnter, preserving the tap path the primitive was written for.

The focus manager records key-up delivery per key as it observes it, exposed as keyDeliversKeyUp / noteKeyUpDelivered. useHold also records from releaseHold, so 'auto' still works behind a custom focus manager.

Value	Behavior
'auto' (default)	Use auto-repeat where the key needs it, fall back to timer where not
false	Always resolve by timer — the legacy keyHoldOptions semantics
true	Require an auto-repeat; never resolve a repeat-less press as a hold

Caveat worth reviewing

'auto' infers from keys observed earlier in the session, so the first press of a given key has no evidence and resolves as a tap. For Back on webOS that means the first hold of a session is missed unless it is stated explicitly:

const [holdBack, releaseBack] = useHold({
  onHold: exitApp,
  onEnter: goBack,
  holdThreshold: 1000,
  holdRequiresRepeat: false, // resolve by timer from the very first press
});

<view onBack={holdBack} onCaptureBackRelease={releaseBack} />;

I kept inference as the default rather than making false the default, since false would regress webOS OK — a short OK press whose key-up is swallowed would fire onHold instead of onEnter. If you would rather not carry the warm-up caveat at all, the alternative is to drop 'auto' and require an explicit value per key; happy to switch.

An early key-up still resolves as a tap under every setting — this only governs the no-key-up and no-repeat case.

Verification

• npm run tsc clean; npm test 170/170 across 15 files; lint at the 152-warning baseline.
• 6 tests added for 'auto' (repeat-swallowing key, key-up-delivering key, early key-up, per-key tracking in one session, no-event case) plus one for strict true.
• Integration test asserts the focus manager's registry populates from real key-ups and stays per-key.

Note this branch also picked up your Release 1.4.1-0 commit while I was working; the new commit sits on top of it.

🤖 Generated with Claude Code