@elcrm/hotkey

Горячие клавиши для elCRM: одна combo, карта действий, import/export, record, format, scopes, sequences.

Установка

npm install @elcrm/hotkey
# или
bun add @elcrm/hotkey

Быстрый старт

import { HotKey } from "@elcrm/hotkey";

function App() {
    HotKey.useKey(() => console.log("save"), "mod+s");
    return (
        <p>
            Сохранить <HotKey.Badge keys="mod+s" />
        </p>
    );
}

Карта действий

export const useAppHotKeys = HotKey.create({
    defaults: {
        save: "mod+s",
        search: "mod+k",
        goInbox: "g i", // sequence
        saveAlt: "mod+s, f2", // несколько combo
    },
    meta: {
        save: {
            label: "Сохранить",
            group: "Файл",
            description: "Сохранить документ",
        },
        search: { label: "Поиск", group: "Навигация" },
    },
    settings: { save: "ctrl+shift+s" },
    storageKey: "elcrm.hotkeys",
    onChange: (settings) => {
        // синк на бэк
        api.saveHotkeys(settings);
    },
});

useAppHotKeys({
    save: () => saveDoc(),
    search: () => openSearch(),
    goInbox: () => go("/inbox"),
});

Импорт / экспорт / конфликты

const result = useAppHotKeys.import('{"save":"ctrl+s"}');
// result.applied, result.skipped, result.conflicts

useAppHotKeys.export();
useAppHotKeys.resolved();
useAppHotKeys.conflicts();
useAppHotKeys.list(); // [{ id, keys, formatted, label, group, description }]
useAppHotKeys.set("search", "mod+p");
useAppHotKeys.reset();
useAppHotKeys.pause();
useAppHotKeys.resume();

Record (запись комбинации)

const [recording, setRecording] = useState(false);

const { combo } = HotKey.useRecord(recording, (next) => {
    useAppHotKeys.set("save", next);
    setRecording(false);
});

<button type="button" onClick={() => setRecording(true)}>
    {recording ? (combo ?? "нажмите клавиши…") : "Изменить"}
</button>

Или императивно: HotKey.record({ onComplete, onCancel }).

Format / Badge

HotKey.format("mod+s"); // "⌘S" | "Ctrl+S"

<HotKey.Badge map={useAppHotKeys} action="save" />
<HotKey.Badge keys="g i" />

Scopes

// Модалка: только её хоткеи
const pop = HotKey.pushScope("modal", { exclusive: true });

HotKey.useKey(onClose, "escape", { scope: "modal" });

// при закрытии
pop();

Глобально: HotKey.pause() / HotKey.resume().

Синтаксис комбинаций

| Запись | Значение | | --- | --- | | "mod+s" | ⌘/Ctrl + S | | ["control","s"] | Ctrl + S | | "mod+s, f2" | либо mod+s, либо F2 | | "g i" | сначала G, потом I |

| Имя | Клавиша | | --- | --- | | mod | ⌘ Mac / Ctrl Win | | control / ctrl, alt, shift, meta / cmd | модификаторы | | escape, enter, space, tab, backspace | спец. | | left / up / right / down | стрелки | | f1…f12 | функциональные |

Опции

useKey(fn, "mod+k", {
    enabled: true,
    preventDefault: true,
    stopPropagation: false,
    ignoreInputs: true,
    allowRepeat: false,
    useCode: true,
    priority: 0,
    scope: "global",
    sequenceTimeout: 1000,
    target: document,
});

Debug

HotKey.debug(true); // логи bind/fire в console