@cartridge-engine/keyboard-engine
    Preparing search index...

    Interface CompositionKey<TComponent, TValue>

    A registered composition key: the trigger key, its flags, and how it transforms the CompositionContext.

    interface CompositionKey<TComponent, TValue = unknown> {
        affectOverlay?: boolean;
        alternativeFlag: string;
        category?: "*" | TComponent[];
        exclusive?: boolean;
        execute?: (
            ctx: CompositionContext<TValue>,
        ) => CompositionContext<TValue> | null;
        executeWhenNoOverlay?: boolean;
        flags: Flags;
        isEndKey?: string[];
        key: string;
        KeyReleaseWhenChainInterrupted?: boolean;
        mode?: string;
        needs: string[];
        optional?: boolean;
        timeout?: number;
        undoAction?: undo<unknown>;
        when?: string | (() => boolean);
    }

    Type Parameters

    • TComponent
    • TValue = unknown

    Hierarchy

    Index
    affectOverlay? alternativeFlag category? exclusive? execute? executeWhenNoOverlay? flags isEndKey? key KeyReleaseWhenChainInterrupted? mode? needs optional? timeout? undoAction? when?
    affectOverlay?: boolean

    Which pipeline phase this entry fires in: true = layer phase (before the layer broadcast), false = page phase (after the layer broadcast, before the screen stack).

    alternativeFlag: string

    Fallback flag used when no needs entry matches, or at the head of a chain.

    category?: "*" | TComponent[]

    Top-component whitelist: "*" or omitted = all screens; [] = no screens (effectively disabled); [A, B] = only when the stack top is exactly A or B.

    exclusive?: boolean

    When true and a needs mismatch occurs mid-sequence, the key is silently consumed (the timeout keeps running). When false or omitted, a mismatched key clears the pending chain and falls through.

    execute?: (ctx: CompositionContext<TValue>) => CompositionContext<TValue> | null

    Transform the composition context when this key fires. Receives the current chain context and returns the modified context passed to the next key in the chain, or null to terminate the chain — the key is then released to lower pipeline stages, or silently swallowed when KeyReleaseWhenChainInterrupted is set.

    executeWhenNoOverlay?: boolean

    When true, an overlay-phase entry (affectOverlay: true) fires even while no layer is open. With the default false, the entry is skipped when no layers exist. Only relevant when affectOverlay is true.

    flags: Flags

    Declare what this key becomes after execution. The next key in the chain uses these flags to recognize its predecessor. Flags are auto-registered when not already known.

    isEndKey?: string[]

    When the chain's current lastFlag is in this list, the key terminates the chain. execute still runs (its side effects happen), but its returned context is discarded and the key is not recorded in the undo buffer — only the keys preceding it are.

    key: string

    Trigger key name(s), e.g. a, B, 3, or "ctrl+s".

    KeyReleaseWhenChainInterrupted?: boolean

    When true and execute returns null, the breaking key is silently swallowed after the chain terminates instead of being released to lower pipeline stages.

    mode?: string

    Restrict the entry to a specific mode. When the active mode does not match, the entry is skipped. Omitted = fires in all modes.

    needs: string[]

    Flags this key expects on the preceding key. When the preceding flag does not match, the key is discarded.

    optional?: boolean

    Whether the preceding flag is optional. When true and no chain is pending, the key executes automatically as a head key. When a chain is already pending, the preceding flag is still checked.

    timeout?: number

    Timeout for the next key press in the sequence, in milliseconds.

    undoAction?: undo<unknown>

    The inverse of execute, run when the sequence is undone. Returning null stops the undo action.

    when?: string | (() => boolean)

    The entry is enabled only while this callback (or named condition id) returns true. Evaluated while filtering candidates, so an entry whose gate is closed is skipped before resolution — a sibling entry for the same key whose gate is open can still match.

    Settings
    Member Visibility

    On This Page
    Properties