ink-cartridge
    Preparing search index...

    Interface EngineProps<TComponent>

    Configuration passed to KeyboardEngine at construction time.

    interface EngineProps<TComponent> {
        autoTab?: boolean;
        defaultMode?: string;
        defaultTimeout?: number;
        isNormalChar: (key: unknown) => boolean;
        modes?: string[];
        normalizeKeyNames: (input: string, key: unknown) => string[];
        processors?: KeyboardProcessorProps<TComponent>[];
        tabKey?: string;
        valueSchema?: ValueSchema;
    }

    Type Parameters

    • TComponent
    Index
    autoTab? defaultMode? defaultTimeout? isNormalChar modes? normalizeKeyNames processors? tabKey? valueSchema?
    autoTab?: boolean

    Whether the engine automatically handles Tab / Shift+Tab for focus rotation. Defaults to false.

    When true, the engine intercepts Tab/Shift+Tab and cycles focus automatically. When false or undefined, developers must call focusNext / focusPrev manually.

    defaultMode?: string

    Default mode — must be null (no-mode) or a member of modes.

    defaultTimeout?: number

    Default composition chain timeout in ms. Defaults to 400.

    isNormalChar: (key: unknown) => boolean

    Determines whether a key is a special key (NOT a normal character).

    Required so the engine stays framework-agnostic — each host framework provides its own adapter that inspects its native Key shape.

    isNormalChar: (key) => {
      const k = key as Record<string, unknown>;
      return k.upArrow || k.downArrow || k.leftArrow || k.rightArrow
        || k.pageDown || k.pageUp || k.home || k.end
        || k.return || k.escape || k.tab || k.backspace || k.delete
        || k.ctrl || k.meta || k.super || k.hyper
        || k.eventType === 'release';
    }
    modes?: string[]

    Registered mode names (e.g. ["normal", "insert"]).

    normalizeKeyNames: (input: string, key: unknown) => string[]

    Converts a framework-specific key event into normalized key-name strings for matching. Required so the engine stays framework-agnostic — each host framework provides its own adapter.

    normalizeKeyNames: (input, key) => normalizeKeyNames(input, key as Key)

    normalizeKeyNames: (input, key) => {
      const e = key as KeyboardEvent
      return [e.key.toLowerCase()]
    }
    processors?: KeyboardProcessorProps<TComponent>[]

    Per-instance custom processors injected into the pipeline at init time.

    tabKey?: string

    Override the key name used for automatic focus rotation when autoTab is true.

    The value must be a key name that normalizeKeyNames can produce — the engine matches via eventNames.includes(thisKey), so the string must exactly match a normalized name the adapter emits.

    When omitted, the engine defaults to "tab" (and "shift+tab" for reverse rotation). Provide a custom value when your host framework's key normalizer produces a different name (e.g. "Tab" with capital T, or "<Tab>").

    // Ink's normalizeKeyNames emits lowercase "tab", so the default works.
    // A framework that normalizes to "Tab" would need:
    new KeyboardEngine({
      normalizeKeyNames,
      autoTab: true,
      tabKey: "Tab",
    });
    valueSchema?: ValueSchema

    Optional runtime type schema for composition chain value validation.

    Maps flag names to type guard functions. When provided, the CompositionEngine validates every execute callback's input and output values at runtime. Validation failures clear the pending chain and emit a console.warn in development.

    const engine = new KeyboardEngine({
      normalizeKeyNames,
      valueSchema: {
        times: (v): v is number => typeof v === 'number',
        action: (v): v is number => typeof v === 'number',
      },
    });

    Settings
    Member Visibility

    On This Page
    Properties