Add lifecycle callbacks for sequence

[juraj98]

Hi, I'd like to add support for lifecycle callbacks on sequences.

Specifically, I want to create transient UI like a "press the next key…" overlay that shows up the moment the user starts a sequence and disappears the moment they bail or time out.

I believe, today the only signal is the completion callback. The best way I could find to achieve this today would be subscribing to the manager's store.

I'd be happy to create PR.

API proposal

Three new optional fields on SequenceOptions:

export interface SequenceCancelContext {
  /** The original hotkey sequence joined with spaces. */
  hotkey: Hotkey
  /** The last successfully matched step in the cancelled attempt. */
  parsedHotkey: ParsedHotkey
  /** How many steps were matched before the cancellation (between 1 and `sequence.length - 1`). */
  matchedStepCount: number
  /** Reason why sequence was cancelled */
  reason: "timeout" | "interrupt" | ...
  /** Optional keyboard event that canceled the sequence. (This is attached to context so we can discriminate the types based on reason) */
  event: KeyboardEvent | undefined
}

interface SequenceOptions {
  // ...existing
  onStart?: (event: KeyboardEvent, context: HotkeyCallbackContext) => void
  onCancel?: (context: SequenceCancelContext) => void
}

• onStart fires when a multi-step sequence advances past its first step. Single-step sequences don't fire it (they complete immediately).
• onCancel fires when the configured timeout between steps elapses without further input, or when the sequence is interrupted. Sequence can be interrupted by when a non-matching key arrives mid-sequence, or when something changes programmatically (such as enabled flipping from true to false)

Right now, "timeout" is only checked when another key is pressed. To track onCancel callback, we'd have to schedule actual timeout via setTimeout. To keep the overhead to minimal, we only schedule it when onCancel is actually provided.

I also considered returning sort of inProgress state from the hook, but I don't believe this is correct solution, as we'd be paying the overhead even when 99% of usecases don't need it.

[KevinVandy]

Part of this works today. Each sequence registration reports matchedStepCount, which goes back to 0 when the sequence times out or is interrupted. So a "press the next key…" overlay can watch the registrations:

const registrations = useHotkeyRegistrations()
const pending = registrations.find(
  (reg) => reg.kind === 'sequence' && reg.matchedStepCount > 0,
)
// Show the overlay while `pending` is set

This is the store subscription you mentioned, wrapped in a hook. There are no onStart or onCancel callbacks yet, so I'm leaving this open.