@peter.naydenov/shortcuts 3.5.2 → 4.0.1

package/dist/src/main.d.ts

@@ -0,0 +1,172 @@
+export type dependencies = {
+    /**
+     * - Event emitter instance
+     */
+    ev: any;
+    /**
+     * - Internal API object
+     */
+    inAPI: any;
+    /**
+     * - Public API object
+     */
+    API: any;
+    /**
+     * - Extra dependencies object
+     */
+    extra: any;
+};
+export type state = {
+    /**
+     * - Current context data container with name and note properties
+     */
+    currentContext: any;
+    /**
+     * - Shortcuts object: { contextName : { shortcut : callback[] } }
+     */
+    shortcuts: any;
+    /**
+     * - Array of active plugins
+     */
+    plugins: any[];
+    /**
+     * - Keyboard shortcut log function
+     */
+    exposeShortcut: Function | null;
+    /**
+     * - Name for error events
+     */
+    ERROR_EVENT_NAME: string;
+};
+export type PluginAPI = {
+    /**
+     * - Get plugin prefix
+     */
+    getPrefix: () => string;
+    /**
+     * - Format shortcut name
+     */
+    shortcutName: (arg0: string) => string;
+    /**
+     * - Handle context change
+     */
+    contextChange: (arg0: string) => void;
+    /**
+     * - Mute the plugin
+     */
+    mute: () => void;
+    /**
+     * - Unmute the plugin
+     */
+    unmute: () => void;
+    /**
+     * - Destroy the plugin
+     */
+    destroy: () => void;
+};
+export type contextShortcuts = {
+    /**
+     * - Context name
+     */
+    context: string;
+    /**
+     * - List of shortcuts in a context
+     */
+    shortcuts: string[];
+};
+export type ShortcutsAPI = {
+    /**
+     * - Enable a plugin
+     */
+    enablePlugin: (arg0: Function, arg1: any) => void;
+    /**
+     * - Disable a plugin
+     */
+    disablePlugin: (arg0: string) => void;
+    /**
+     * - Mute a plugin
+     */
+    mutePlugin: (arg0: string) => number;
+    /**
+     * - Unmute a plugin
+     */
+    unmutePlugin: (arg0: string) => number;
+    /**
+     * - List enabled plugins
+     */
+    listPlugins: () => string[];
+    /**
+     * - Get current context name
+     */
+    getContext: () => string | null;
+    /**
+     * - Get current context note
+     */
+    getNote: () => string | null;
+    /**
+     * - Set current context note
+     */
+    setNote: (arg0: string | null) => void;
+    /**
+     * - Pause shortcuts in current context
+     */
+    pause: (arg0: string) => void;
+    /**
+     * - Resume shortcuts in current context
+     */
+    resume: (arg0: string) => void;
+    /**
+     * - Emit event for shortcut
+     */
+    emit: (arg0: string, ...args: any[]) => void;
+    /**
+     * - List all context names
+     */
+    listContexts: () => string[];
+    /**
+     * - Set external dependencies
+     */
+    setDependencies: (arg0: any) => void;
+    /**
+     * - Get external dependencies
+     */
+    getDependencies: () => any;
+    /**
+     * - Reset the library instance
+     */
+    reset: () => void;
+    /**
+     * - Change current context
+     */
+    changeContext: (arg0: string | boolean) => void;
+    /**
+     * - List shortcuts
+     */
+    listShortcuts: (arg0: string | null) => string[] | contextShortcuts[] | null;
+    /**
+     * - Load shortcuts into contexts
+     */
+    load: (arg0: any) => void;
+    /**
+     * - Unload a context
+     */
+    unload: (arg0: string) => void;
+};
+/**
+ * @function shortcuts
+ * @description Create a shortcuts instance
+ * @param {Object} [options={}] - Configuration options
+ * @param {function} [options.onShortcut] - Function to log shortcut events
+ * @param {string} [options.errorEventName='@shortcuts-error'] - Name for error events
+ * @returns {ShortcutsAPI} The shortcuts API
+ */
+declare function main(options?: {
+    onShortcut?: Function;
+    errorEventName?: string;
+}): ShortcutsAPI;
+import pluginKey from './plugins/key/index.js';
+import pluginClick from './plugins/click/index.js';
+import pluginForm from './plugins/form/index.js';
+import pluginHover from './plugins/hover/index.js';
+import pluginScroll from './plugins/scroll/index.js';
+export { main as shortcuts, pluginKey, pluginClick, pluginForm, pluginHover, pluginScroll };

package/dist/src/methods/_normalizeWithPlugins.d.ts

@@ -0,0 +1,64 @@
+export default _normalizeWithPlugins;
+export type dependencies = {
+    /**
+     * - Event emitter instance
+     */
+    ev: any;
+    /**
+     * - Internal API object
+     */
+    inAPI: any;
+    /**
+     * - Public API object
+     */
+    API: any;
+    /**
+     * - Extra dependencies object
+     */
+    extra: any;
+};
+export type state = {
+    /**
+     * - Current context data container
+     */
+    currentContext: any;
+    /**
+     * - Shortcuts object: { contextName : { shortcut : callback[] } }
+     */
+    shortcuts: any;
+    /**
+     * - Array of active plugins
+     */
+    plugins: any[];
+    /**
+     * - Keyboard shortcut log function
+     */
+    exposeShortcut: Function | null;
+    /**
+     * - Name for error events
+     */
+    ERROR_EVENT_NAME: string;
+};
+/**
+ * @typedef {Object} dependencies
+ * @property {Object} ev - Event emitter instance
+ * @property {Object} inAPI - Internal API object
+ * @property {Object} API - Public API object
+ * @property {Object} extra - Extra dependencies object
+ */
+/**
+ * @typedef {Object} state
+ * @property {Object} currentContext - Current context data container
+ * @property {Object} shortcuts - Shortcuts object: { contextName : { shortcut : callback[] } }
+ * @property {Array} plugins - Array of active plugins
+ * @property {Function|null} exposeShortcut - Keyboard shortcut log function
+ * @property {string} ERROR_EVENT_NAME - Name for error events
+ */
+/**
+ * @function _normalizeWithPlugins
+ * @description Function used by plugins during the enable process to normalize the existing and related to the plugin shortcut names.
+ * @param {dependencies} dependencies - Dependencies object containing inAPI
+ * @param {state} state - State object containing shortcuts
+ * @returns {function} - Returns a function that takes a normalize function
+ */
+declare function _normalizeWithPlugins(dependencies: dependencies, state: state): Function;

package/dist/src/methods/_readShortcutWithPlugins.d.ts

@@ -0,0 +1,9 @@
+export default _readShortcutWithPlugins;
+/**
+ * @function _readShortcutWithPlugins
+ * @description Searches for belonging plugin and call the plugin method to normalize the shortcut name.
+ * @param {dependencies} dependencies - Dependencies object containing inAPI
+ * @param {state} state - State object containing plugins
+ * @returns {function} - Returns a function that processes shortcut names
+ */
+declare function _readShortcutWithPlugins(dependencies: any, state: any): Function;

package/dist/src/methods/_setupPlugin.d.ts

@@ -0,0 +1,9 @@
+export default _setupPlugin;
+/**
+ * @function _setupPlugin
+ * @description Setup a plugin with provided settings and dependencies
+ * @param {dependencies} dependencies - Dependencies object containing ev, extra, inAPI, API
+ * @param {state} state - State object containing currentContext, shortcuts, exposeShortcut, ERROR_EVENT_NAME
+ * @returns {function} - Returns a function that takes plugin settings and returns plugin API
+ */
+declare function _setupPlugin(dependencies: any, state: any): Function;

package/dist/src/methods/_systemAction.d.ts

@@ -0,0 +1,9 @@
+export default _systemAction;
+/**
+ * @function _systemAction
+ * @description Call a specific plugin method.
+ * @param {dependencies} dependencies - Dependencies object containing inAPI
+ * @param {state} state - State object containing plugins array
+ * @returns {function} - Returns a function that executes plugin actions
+ */
+declare function _systemAction(dependencies: any, state: any): Function;

package/dist/src/methods/changeContext.d.ts

@@ -0,0 +1,9 @@
+export default changeContext;
+/**
+ * @function changeContext
+ * @description Change current context with shortcuts belonging to it
+ * @param {dependencies} dependencies - Dependencies object containing ev
+ * @param {state} state - State object containing shortcuts, currentContext, ERROR_EVENT_NAME
+ * @returns {function} - Returns a function that changes context
+ */
+declare function changeContext(dependencies: any, state: any): Function;

package/dist/src/methods/index.d.ts

@@ -0,0 +1,19 @@
+declare namespace _default {
+    export { _normalizeWithPlugins };
+    export { _readShortcutWithPlugins };
+    export { _setupPlugin };
+    export { _systemAction };
+    export { changeContext };
+    export { listShortcuts };
+    export { load };
+    export { unload };
+}
+export default _default;
+import _normalizeWithPlugins from './_normalizeWithPlugins.js';
+import _readShortcutWithPlugins from './_readShortcutWithPlugins.js';
+import _setupPlugin from './_setupPlugin.js';
+import _systemAction from './_systemAction.js';
+import changeContext from './changeContext.js';
+import listShortcuts from './listShortcuts.js';
+import load from './load.js';
+import unload from './unload.js';

package/dist/src/methods/listShortcuts.d.ts

@@ -0,0 +1,2 @@
+export default listShortcuts;
+declare function listShortcuts(dependencies: any, state: any): (contextName?: string | null) => string[] | contextShortcuts[] | null;

package/dist/src/methods/load.d.ts

@@ -0,0 +1,9 @@
+export default load;
+/**
+ * @function load
+ * @description Load a context with shortcuts object
+ * @param {dependencies} dependencies - Dependencies object containing API with changeContext and getContext
+ * @param {state} state - State object containing shortcuts and plugins
+ * @returns {function} - Returns a function that loads shortcuts
+ */
+declare function load(dependencies: any, state: any): Function;

package/dist/src/methods/unload.d.ts

@@ -0,0 +1,9 @@
+export default unload;
+/**
+ * @function unload
+ * @description Unload a non-active context with shortcuts
+ * @param {dependencies} dependencies - Dependencies object containing ev
+ * @param {state} state - State object containing currentContext, shortcuts, ERROR_EVENT_NAME
+ * @returns {function} - Returns a function that unloads contexts
+ */
+declare function unload(dependencies: any, state: any): Function;

package/dist/src/plugins/click/_findTarget.d.ts

@@ -0,0 +1,10 @@
+export default _findTarget;
+/**
+ * @function _findTarget
+ * @description Find the appropriate click target element by checking if element has any of the target attributes
+ * @param {Object} dependencies - Dependencies object
+ * @param {Object} state - Plugin state containing listenOptions with clickTarget array
+ * @param {Element} target - DOM element to start searching from
+ * @returns {Element|null} - Target element or null if not found
+ */
+declare function _findTarget(dependencies: any, state: any, target: Element): Element | null;

package/dist/src/plugins/click/_listenDOM.d.ts

@@ -0,0 +1,78 @@
+export default _listenDOM;
+export type ClickEventData = {
+    /**
+     * - The DOM element that was clicked
+     */
+    target: Element;
+    /**
+     * - X coordinate of the click event
+     */
+    x: number;
+    /**
+     * - Y coordinate of the click event
+     */
+    y: number;
+    /**
+     * - Current context name
+     */
+    context: string;
+    /**
+     * - Current context note
+     */
+    note: string | null;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+    /**
+     * - The original DOM event
+     */
+    event: Event;
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Viewport information with X, Y, width, height
+     */
+    viewport: any;
+    /**
+     * - Element dimensions with width, height
+     */
+    sizes: any;
+    /**
+     * - Element position relative to viewport with x, y
+     */
+    position: any;
+    /**
+     * - Element position relative to page with x, y
+     */
+    pagePosition: any;
+    /**
+     * - Event type ('click')
+     */
+    type: string;
+};
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for click events
+ * @param {Object} dependencies - Dependencies object containing ev, _findTarget, _readClickEvent, extra, resetState
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ *
+ * @typedef {Object} ClickEventData
+ * @property {Element} target - The DOM element that was clicked
+ * @property {number} x - X coordinate of the click event
+ * @property {number} y - Y coordinate of the click event
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * @property {Event} event - The original DOM event
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} viewport - Viewport information with X, Y, width, height
+ * @property {Object} sizes - Element dimensions with width, height
+ * @property {Object} position - Element position relative to viewport with x, y
+ * @property {Object} pagePosition - Element position relative to page with x, y
+ * @property {string} type - Event type ('click')
+ */
+declare function _listenDOM(dependencies: any, state: any): any;

package/dist/src/plugins/click/_normalizeShortcutName.d.ts

@@ -0,0 +1,8 @@
+export default _normalizeShortcutName;
+/**
+ * @function _normalizeShortcutName
+ * @description Normalize click shortcut name to standard format
+ * @param {string} name - Raw shortcut name
+ * @returns {string} - Normalized shortcut name
+ */
+declare function _normalizeShortcutName(name: string): string;

package/dist/src/plugins/click/_readClickEvent.d.ts

@@ -0,0 +1,2 @@
+export default _readClickEvent;
+declare function _readClickEvent(event: any, count: any): string;

package/dist/src/plugins/click/_registerShortcutEvents.d.ts

@@ -0,0 +1,28 @@
+export default _registerShortcutEvents;
+export type ClickSetupData = {
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Default options (clone of pluginState.defaultOptions)
+     */
+    defaults: any;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+};
+/**
+ * @function _registerShortcutEvents
+ * @description Register click shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex
+ * @param {Object} pluginState - Plugin state containing listenOptions, currentContext, shortcuts, etc.
+ * @returns {number} - Number of registered shortcuts
+ *
+ * @typedef {Object} ClickSetupData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} defaults - Default options (clone of pluginState.defaultOptions)
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ */
+declare function _registerShortcutEvents(dependencies: any, pluginState: any): number;

package/dist/src/plugins/click/index.d.ts

@@ -0,0 +1,16 @@
+export default pluginClick;
+/**
+ * @function pluginClick
+ * @description Plugin for mouse click shortcuts
+ * @param {function} setupPlugin - Plugin setup function from the library
+ * @param {Object} [options={}] - Plugin options
+ * @param {number} [options.mouseWait=320] - Time to wait for click sequence in ms
+ * @param {string[]} [options.clickTarget=['data-click', 'href']] - Array of attribute names for click targets
+ * @param {function} [options.streamKeys] - Function to stream key presses
+ * @returns {PluginAPI} Plugin API
+ */
+declare function pluginClick(setupPlugin: Function, options?: {
+    mouseWait?: number;
+    clickTarget?: string[];
+    streamKeys?: Function;
+}): PluginAPI;

package/dist/src/plugins/form/_defaults.d.ts

@@ -0,0 +1,17 @@
+export default _defaults;
+export type _defaults = {
+    /**
+     * - Function that returns CSS selector for form elements to watch
+     */
+    watch: Function;
+    /**
+     * - Function that determines the type of form element
+     */
+    define: Function;
+};
+declare namespace _defaults {
+    function watch(): string;
+    function define({ target }: {
+        target: any;
+    }): "input" | "checkbox" | "button";
+}

package/dist/src/plugins/form/_listenDOM.d.ts

@@ -0,0 +1,68 @@
+export default _listenDOM;
+export type FormEventData = {
+    /**
+     * - The DOM element that triggered the form event
+     */
+    target: Element;
+    /**
+     * - Current context name
+     */
+    context: string;
+    /**
+     * - Current context note
+     */
+    note: string | null;
+    /**
+     * - The original DOM event
+     */
+    event: Event;
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+    /**
+     * - Viewport information with X, Y, width, height
+     */
+    viewport: any;
+    /**
+     * - Element dimensions with width, height
+     */
+    sizes: any;
+    /**
+     * - Element position relative to viewport with x, y
+     */
+    position: any;
+    /**
+     * - Element position relative to page with x, y
+     */
+    pagePosition: any;
+    /**
+     * - Event type ('form-in', 'form-out', 'form-instant')
+     */
+    type: string;
+};
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for form events
+ * @param {Object} dependencies - Dependencies object containing ev
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ *
+ * @typedef {Object} FormEventData
+ * @property {Element} target - The DOM element that triggered the form event
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Event} event - The original DOM event
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * @property {Object} viewport - Viewport information with X, Y, width, height
+ * @property {Object} sizes - Element dimensions with width, height
+ * @property {Object} position - Element position relative to viewport with x, y
+ * @property {Object} pagePosition - Element position relative to page with x, y
+ * @property {string} type - Event type ('form-in', 'form-out', 'form-instant')
+ */
+declare function _listenDOM(dependencies: any, state: any): any;

package/dist/src/plugins/form/_normalizeShortcutName.d.ts

@@ -0,0 +1,2 @@
+export default _normalizeShortcutName;
+declare function _normalizeShortcutName(name: any): any;

package/dist/src/plugins/form/_registerShortcutEvents.d.ts

@@ -0,0 +1,96 @@
+export default _registerShortcutEvents;
+export type FormWatchData = {
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Current context name
+     */
+    context: string;
+    /**
+     * - Current context note
+     */
+    note: string | null;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+};
+export type FormDefineData = {
+    /**
+     * - The DOM element being watched
+     */
+    target: Element;
+    /**
+     * - Current context name
+     */
+    context: string;
+    /**
+     * - Current context note
+     */
+    note: string | null;
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Viewport information with X, Y, width, height
+     */
+    viewport: any;
+    /**
+     * - Element dimensions with width, height
+     */
+    sizes: any;
+    /**
+     * - Element position relative to viewport with x, y
+     */
+    position: any;
+    /**
+     * - Element position relative to page with x, y
+     */
+    pagePosition: any;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+};
+export type FormActionData = {
+    /**
+     * - Extra dependencies object
+     */
+    dependencies: any;
+    /**
+     * - Plugin state listenOptions (reference to pluginState.listenOptions)
+     */
+    options: any;
+};
+/**
+ * @function _registerShortcutEvents
+ * @description Register form shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex, _defaults, ev
+ * @param {Object} pluginState - Plugin state containing currentContext, shortcuts, callbacks, etc.
+ * @returns {number|false} - Number of registered shortcuts or false if no actions
+ *
+ * @typedef {Object} FormWatchData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ *
+ * @typedef {Object} FormDefineData
+ * @property {Element} target - The DOM element being watched
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} viewport - Viewport information with X, Y, width, height
+ * @property {Object} sizes - Element dimensions with width, height
+ * @property {Object} position - Element position relative to viewport with x, y
+ * @property {Object} pagePosition - Element position relative to page with x, y
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ *
+ * @typedef {Object} FormActionData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ */
+declare function _registerShortcutEvents(dependencies: any, pluginState: any): number | false;

package/dist/src/plugins/form/index.d.ts

@@ -0,0 +1,9 @@
+export default pluginForm;
+/**
+ * @function pluginForm
+ * @description Plugin for form element shortcuts
+ * @param {function} setupPlugin - Plugin setup function from the library
+ * @param {Object} [options={}] - Plugin options
+ * @returns {PluginAPI} Plugin API
+ */
+declare function pluginForm(setupPlugin: Function, options?: any): PluginAPI;

package/dist/src/plugins/hover/_findTarget.d.ts

@@ -0,0 +1,10 @@
+export default _findTarget;
+/**
+ * @function _findTarget
+ * @description Find the appropriate hover target element by checking if element has any of the target attributes
+ * @param {Object} dependencies - Dependencies object
+ * @param {Object} state - Plugin state containing listenOptions with hoverTarget array
+ * @param {Element} target - DOM element to start searching from
+ * @returns {Element|false} - Target element or false if not found
+ */
+declare function _findTarget(dependencies: any, state: any, target: Element): Element | false;