import { Subscription } from '@napplet/core';

/**
 * Napplet NAP keys sdk entrypoint.
 *
 * @module
 */
/**
 * @napplet/nap/keys -- SDK helpers wrapping window.napplet.keys.
 *
 * These convenience functions delegate to `window.napplet.keys.*` at call time.
 * The shim must be imported somewhere to install the global.
 */

/**
 * Declare a named action that the shell can bind to a key.
 *
 * @param action  The action to register (id, label, optional defaultKey)
 * @returns The assigned binding, if any
 *
 * @example
 * ```ts
 * import { keysRegisterAction } from '@napplet/nap/keys';
 *
 * const result = await keysRegisterAction({
 *   id: 'editor.save',
 *   label: 'Save',
 *   defaultKey: 'Ctrl+S',
 * });
 * ```
 */
declare function keysRegisterAction(action: {
    id: string;
    label: string;
    defaultKey?: string;
}): Promise<{
    actionId: string;
    binding?: string;
}>;
/**
 * Remove a previously registered action.
 *
 * @param actionId  The action to unregister
 *
 * @example
 * ```ts
 * import { keysUnregisterAction } from '@napplet/nap/keys';
 *
 * keysUnregisterAction('editor.save');
 * ```
 */
declare function keysUnregisterAction(actionId: string): void;
/**
 * Register a local handler for when a bound key is pressed.
 *
 * @param actionId  The action to listen for
 * @param callback  Called when the action is triggered
 * @returns A Subscription with `close()` to stop listening
 *
 * @example
 * ```ts
 * import { keysOnAction } from '@napplet/nap/keys';
 *
 * const sub = keysOnAction('editor.save', () => {
 *   console.log('Save triggered!');
 * });
 * // Later: sub.close();
 * ```
 */
declare function keysOnAction(actionId: string, callback: () => void): Subscription;
/**
 * Convenience: register a named action AND wire a local handler in one call.
 * Returns a handle whose `close()` both unregisters the action and removes
 * the onAction listener.
 *
 * @param action   The action to register (id, label, optional defaultKey)
 * @param handler  Called when the shell triggers this action
 * @returns The assigned binding plus a `close()` teardown function
 *
 * @example
 * ```ts
 * import { keysRegister } from '@napplet/nap/keys';
 *
 * const handle = await keysRegister(
 *   { id: 'editor.save', label: 'Save', defaultKey: 'Ctrl+S' },
 *   () => saveDocument(),
 * );
 *
 * // Later, tear down both registration and listener:
 * handle.close();
 * ```
 */
declare function keysRegister(action: {
    id: string;
    label: string;
    defaultKey?: string;
}, handler: () => void): Promise<{
    actionId: string;
    binding?: string;
    close: () => void;
}>;

export { keysOnAction, keysRegister, keysRegisterAction, keysUnregisterAction };