Documentation
    Preparing search index...

    Interface KeysServiceOptions

    Options for creating a keys service via createKeysService().

    const keys = createKeysService({
      onForward: (event) => {
        // event has DOM-compatible field names: ctrlKey, altKey, etc.
        hotkeyDispatcher.dispatch(event);
      },
    });
    interface KeysServiceOptions {
        hostBridge?: HostKeysBridge;
        listenerTarget?: EventTarget;
        onForward?: (
            event: {
                altKey: boolean;
                code: string;
                ctrlKey: boolean;
                key: string;
                metaKey: boolean;
                shiftKey: boolean;
            },
        ) => void;
        reservedChords?: readonly string[];
    }
    Index

    Properties

    hostBridge? listenerTarget? onForward? reservedChords?

    Properties

    hostBridge?: HostKeysBridge

    Optional pluggable backend for chord subscription. When provided, the service delegates keys.registerAction → bridge.subscribe(chord, cb) and stores the returned unsubscribe handle keyed on actionId. The default document-listener path is NOT attached when hostBridge is provided — the bridge is authoritative. See HostKeysBridge.

    listenerTarget?: EventTarget

    EventTarget to attach the default keydown listener to. Defaults to the global document when running in a DOM environment, else an isolated new EventTarget() (SSR / Node-test safe). Passing a fresh new EventTarget() is useful for unit tests. Mirrors the pattern used by @kehto/shell's createKeysForwarder.

    Ignored when hostBridge is provided — the bridge owns subscription lifecycle and no document listener is attached.

    onForward?: (
        event: {
            altKey: boolean;
            code: string;
            ctrlKey: boolean;
            key: string;
            metaKey: boolean;
            shiftKey: boolean;
        },
    ) => void

    Called on keys.forward (napplet-forwarded chord) AND on document keydown matching a registered action. Receives the DOM-style field names (ctrlKey/altKey/shiftKey/metaKey) to match the shell's HotkeyHooks contract. The service translates from the wire shape ({ ctrl, alt, shift, meta }) before invoking this callback.

    reservedChords?: readonly string[]

    Optional set of shell-reserved chords. Strings in the @napplet/nap/keys wire format (e.g. 'Ctrl+Shift+K', 'Cmd+P'). When a napplet sends keys.forward with a chord matching this set — or when a document keydown matches a reserved chord — the service invokes onForward (or the hostBridge-registered handler) but suppresses the keys.action push to any napplet that registered the same chord via keys.registerAction. Precedence: reserved > registered. The shell WANTS the forward — that is why it reserved the chord.

    Normalized once at service construction via the same chord parser used for action.defaultKey — 'Ctrl+K' / 'Control+k' / 'ctrl+K' all match. Static; no runtime mutation. For dynamic reservation see the deferred HostKeysBridge.reserveAbsolute(chords) extension.

    const keys = createKeysService({
      reservedChords: ['Ctrl+Alt+T', 'Super+Space'],
      onForward: (event) => wm.dispatch(event),
    });

    Settings

    Member Visibility

    On This Page

    Properties