@dolphy-app/keybindings 0.4.0

package/README.md

@@ -0,0 +1,24 @@
+# @dolphy-app/keybindings
+
+Keybinding registry core: key notation, platform and layout aware matching, when-clauses, precedence and conflict detection
+
+The package version equals the version of the Dolphy app release it was published from (0.4.0).
+
+Framework-free keybinding registry core: key notation with a
+platform-aware `Mod`, layout-aware matching of keyboard events,
+`when` clauses with overlap analysis, a keymap with source precedence
+and conflict detection. No DOM and no dependencies.
+
+```ts
+import { buildKeymap, parseChord } from '@dolphy-app/keybindings';
+```
+
+## Installation
+
+```sh
+npm install @dolphy-app/keybindings
+```
+
+## Documentation
+
+[Dolphy extensions](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+//#region packages/keybindings/src/platform.d.ts
+type Platform = 'mac' | 'windows' | 'linux';
+export declare const PLATFORMS: readonly Platform[];
+interface NavigatorLike {
+  readonly platform?: string;
+  readonly userAgent?: string;
+}
+/** Платформа окна по `navigator`: Mac, Windows, всё остальное — Linux. */
+export declare const detectPlatform: (nav: NavigatorLike) => Platform;
+/** Платформа процесса Node по `process.platform`. */
+export declare const platformFromNode: (name: string) => Platform;
+//#endregion
+//#region packages/keybindings/src/keystroke.d.ts
+/**
+ * Одно нажатие: модификаторы и клавиша. `key` — логическое имя в нижнем
+ * регистре (`k`, `,`, `enter`, `arrowup`, `f5`), `code` — физическая клавиша
+ * (`KeyK`) для записи `[KeyK]`; задано ровно одно из двух. `Mod` в нажатии
+ * уже раскрыт в Ctrl или Meta.
+ */
+interface Keystroke {
+  readonly ctrl: boolean;
+  readonly alt: boolean;
+  readonly shift: boolean;
+  readonly meta: boolean;
+  readonly key: string;
+  readonly code: string;
+}
+/** Сочетание: одно нажатие или цепочка из двух. */
+type Chord = readonly Keystroke[];
+export declare const MAX_CHORD_LENGTH = 2;
+type SyntaxReason = 'empty' | 'empty-part' | 'too-long' | 'modifier-only' | 'unknown-modifier' | 'repeated-modifier' | 'unknown-key' | 'invalid-code';
+export declare class KeybindingSyntaxError extends Error {
+  readonly reason: SyntaxReason;
+  readonly text: string;
+  constructor(reason: SyntaxReason, text: string);
+}
+/** Логическая клавиша, которую даёт физическая: `KeyK` → `k`, `Comma` → `,`; нет соответствия — `undefined`. */
+export declare const codeToKey: (code: string) => string | undefined;
+/**
+ * `Mod+Shift+L` или `Mod+K Mod+S` → сочетание для платформы. `Mod` — Meta на
+ * macOS и Ctrl на остальных; остальные модификаторы — по имени. Ошибка
+ * записи — `KeybindingSyntaxError` с причиной.
+ */
+export declare const parseChord: (text: string, platform: Platform) => Chord;
+/** `null` вместо ошибки. */
+export declare const tryParseChord: (text: string, platform: Platform) => Chord | null;
+/** Каноническая запись для хранения: `Mod` вместо основного модификатора платформы. */
+export declare const chordToText: (chord: Chord, platform: Platform) => string;
+/** Подпись для интерфейса: `⇧⌘L` на macOS, `Ctrl+Shift+L` на остальных; цепочка — через пробел. */
+export declare const formatChord: (chord: Chord, platform: Platform) => string;
+/** Идентификаторы слов, которыми озвучивается сочетание (тексты — `keybinding.*` в общих сообщениях). */
+type SpokenId = 'command' | 'control' | 'windows' | 'super' | 'shift' | 'option' | 'alt' | 'comma' | 'plus' | 'enter' | 'escape' | 'tab' | 'space' | 'backspace' | 'delete' | 'insert' | 'home' | 'end' | 'pageup' | 'pagedown' | 'arrowup' | 'arrowdown' | 'arrowleft' | 'arrowright';
+/**
+ * Сочетание словами для скринридера: `⌘K` без этого читается как набор
+ * символов. На macOS — «Command Option Shift L», иначе — «Control Alt Shift L»;
+ * нажатия цепочки разделены запятой.
+ */
+export declare const spokenChord: (chord: Chord, platform: Platform, word: (id: SpokenId) => string) => string;
+/**
+ * Ключ сравнения нажатия: модификаторы и клавиша. Физическая клавиша, у
+ * которой есть логическое имя (`[KeyK]`), приравнена к нему (`k`): на любой
+ * раскладке такие записи могут сработать от одного нажатия.
+ */
+export declare const strokeKey: (item: Keystroke) => string;
+/** Сочетание начинается нажатиями `prefix` (или совпадает с ним). */
+export declare const chordStartsWith: (chord: Chord, prefix: Chord) => boolean;
+/**
+ * Первое нажатие печатает или правит текст (`K`, `Shift+K`, `,`, `Enter`,
+ * стрелки): без Ctrl и Meta такое сочетание срабатывало бы при наборе. Не
+ * считаются `Escape` и F1–F24.
+ */
+export declare const isTypingChord: (chord: Chord) => boolean;
+/** Событие клавиатуры в том виде, который нужен сопоставлению (подмножество `KeyboardEvent`). */
+interface KeyEventLike {
+  readonly key: string;
+  readonly code: string;
+  readonly ctrlKey: boolean;
+  readonly shiftKey: boolean;
+  readonly altKey: boolean;
+  readonly metaKey: boolean;
+  readonly isComposing?: boolean;
+  getModifierState?(name: string): boolean;
+}
+/**
+ * Событие совпадает с нажатием. Модификаторы — ровно заданные (AltGr не
+ * считается Ctrl+Alt). Физическая запись сверяется по `code`. Логическая — по
+ * `event.key`: буква ASCII окончательна (Dvorak, Colemak, AZERTY); если `key`
+ * не ASCII-буква (русская раскладка, мёртвые клавиши, ⌥+буква на macOS),
+ * клавишу определяет `code`. Событие во время IME-ввода не совпадает.
+ */
+export declare const matchKeystroke: (event: KeyEventLike, expected: Keystroke) => boolean;
+/**
+ * Событие в нажатие для записи сочетания в интерфейсе; `null` — одиночный
+ * модификатор или клавиша без имени. Именованные клавиши и буква ASCII
+ * записываются по `key`, остальное — по логическому имени физической клавиши
+ * (`KeyK` на русской раскладке → `k`), без имени — физической записью.
+ */
+export declare const eventToKeystroke: (event: KeyEventLike) => Keystroke | null;
+//#endregion
+//#region packages/keybindings/src/when.d.ts
+/**
+ * Условие привязки (`when`): ключ, `!ключ`, `ключ == значение`,
+ * `ключ != значение`, `&&`, `||`, скобки. `!` стоит только перед ключом или
+ * группой в скобках. Приоритет: `!`, затем `&&`, затем `||`.
+ */
+type WhenExpr = {
+  readonly type: 'key';
+  readonly key: string;
+} | {
+  readonly type: 'not';
+  readonly expr: WhenExpr;
+} | {
+  readonly type: 'eq';
+  readonly key: string;
+  readonly value: string;
+} | {
+  readonly type: 'neq';
+  readonly key: string;
+  readonly value: string;
+} | {
+  readonly type: 'and';
+  readonly terms: readonly WhenExpr[];
+} | {
+  readonly type: 'or';
+  readonly terms: readonly WhenExpr[];
+};
+export declare const WHEN_MAX_LENGTH = 256;
+type WhenReason = 'empty' | 'too-long' | 'too-deep' | 'unexpected-token' | 'unexpected-end' | 'unterminated-string';
+export declare class WhenSyntaxError extends Error {
+  readonly reason: WhenReason;
+  /** Позиция ошибки в тексте (индекс символа). */
+  readonly position: number;
+  constructor(reason: WhenReason, position: number);
+}
+/** Текст условия → выражение; ошибка — `WhenSyntaxError` с причиной и позицией. */
+export declare const parseWhen: (text: string) => WhenExpr;
+/** `null` вместо ошибки. */
+export declare const tryParseWhen: (text: string) => WhenExpr | null;
+/** Каноническая запись выражения (скобки только где нужны). */
+export declare const whenToText: (expr: WhenExpr, parent?: number) => string;
+/** Значение контекстного ключа; `undefined` — ключ не задан. */
+type ContextLookup = (key: string) => unknown;
+/**
+ * Выражение истинно в контексте. `null` (нет условия) — всегда истина;
+ * неизвестный ключ — ложь; сравнение — по строковому виду значения, у
+ * незаданного ключа `==` ложно, а `!=` истинно.
+ */
+export declare const evaluateWhen: (expr: WhenExpr | null, lookup: ContextLookup) => boolean;
+/**
+ * Могут ли оба условия быть истинными одновременно. `null` — нет условия.
+ * Сверх 64 термов в нормальной форме ответ «да» (лучше лишнее предупреждение,
+ * чем молчание).
+ */
+export declare const whenOverlaps: (left: WhenExpr | null, right: WhenExpr | null) => boolean;
+//#endregion
+//#region packages/keybindings/src/keymap.d.ts
+/** Откуда привязка: код приложения, вклад расширения, настройки пользователя. */
+type BindingSource = 'default' | 'extension' | 'user';
+/** Привязка из кода приложения или вклада расширения; `mac`/`windows`/`linux` заменяют `key` на своей платформе. */
+interface BindingDefinition {
+  readonly command: string;
+  readonly key: string;
+  readonly mac?: string | null;
+  readonly windows?: string | null;
+  readonly linux?: string | null;
+  readonly when?: string | null;
+}
+interface UserBindingEntry {
+  readonly key: string;
+  readonly when: string | null;
+}
+/** Набор пользователя по ключам команд: заменяет привязки команды целиком (пустой — «снято»). */
+type UserKeybindings = Readonly<Record<string, readonly UserBindingEntry[]>>;
+interface Binding {
+  readonly command: string;
+  readonly source: BindingSource;
+  /** Запись клавиш для платформы окна, как задана. */
+  readonly text: string;
+  readonly chord: Chord;
+  readonly when: WhenExpr | null;
+  readonly whenText: string | null;
+  /** Чем больше, тем выше приоритет. */
+  readonly rank: number;
+}
+/** Запись, которую не удалось разобрать: карта её пропускает и сообщает. */
+interface BindingIssue {
+  readonly source: BindingSource;
+  readonly command: string;
+  readonly key: string;
+  readonly when: string | null;
+  readonly field: 'key' | 'when';
+  readonly reason: string;
+}
+interface KeymapInput {
+  readonly platform: Platform;
+  readonly defaults: readonly BindingDefinition[];
+  readonly extensions: readonly BindingDefinition[];
+  readonly user: UserKeybindings;
+}
+type Resolution = {
+  readonly kind: 'none';
+} | {
+  readonly kind: 'pending';
+  readonly binding: Binding;
+} | {
+  readonly kind: 'run';
+  readonly binding: Binding;
+};
+/**
+ * Пересечение привязок разных команд: `same` — клавиши совпадают, `prefix` —
+ * клавиши одной начинают цепочку другой; условия пересекаются. Побеждает
+ * привязка с большим приоритетом.
+ */
+interface Conflict {
+  readonly kind: 'same' | 'prefix';
+  readonly winner: Binding;
+  readonly loser: Binding;
+}
+interface Keymap {
+  /** Действующие привязки по убыванию приоритета. */
+  readonly bindings: readonly Binding[];
+  readonly issues: readonly BindingIssue[];
+  /** Привязки команды по убыванию приоритета. */
+  forCommand(command: string): readonly Binding[];
+  /**
+   * Нажатия с начала цепочки (последнее — текущее): `run` — выполнить
+   * команду, `pending` — ждать следующее нажатие, `none` — привязки нет.
+   * Недоступные команды (`isEnabled`) и привязки с ложным условием не
+   * участвуют.
+   */
+  resolve(presses: readonly KeyEventLike[], lookup: ContextLookup, isEnabled?: (command: string) => boolean): Resolution;
+  conflicts(): readonly Conflict[];
+}
+/**
+ * Собирает действующие привязки: набор пользователя заменяет привязки команды
+ * из кода и расширений целиком; приоритет `user` > `default` > `extension`,
+ * внутри источника позднее выше. Записи, которые не разбираются (повреждённые
+ * данные), пропускаются и попадают в `issues`.
+ */
+export declare const buildKeymap: (input: KeymapInput) => Keymap;
+interface Candidate {
+  readonly command: string;
+  readonly chord: Chord;
+  readonly when: WhenExpr | null;
+}
+/**
+ * Пересечения кандидата с действующими привязками **других** команд (набор
+ * самой команды заменяется кандидатами, поэтому его привязки не сравниваются).
+ * Для интерфейса записи сочетания: список до сохранения.
+ */
+export declare const findCandidateConflicts: (keymap: Keymap, candidate: Candidate) => Conflict[];
+//#endregion
+//#region packages/keybindings/src/validate.d.ts
+export declare const KEY_MAX_LENGTH = 64;
+type BindingProblem = {
+  readonly field: 'key';
+  readonly reason: 'syntax';
+  readonly detail: SyntaxReason | 'too-long-text';
+} | {
+  readonly field: 'when';
+  readonly reason: 'syntax';
+  readonly detail: WhenReason;
+  readonly position: number;
+} | {
+  readonly field: 'when';
+  readonly reason: 'typing';
+  readonly detail: 'typing';
+};
+/**
+ * Проверка привязки: клавиши (на каждой из `platforms`: `Mod` раскрывается по
+ * платформе, и запись вроде `Mod+Ctrl+K` верна не везде), условие и правило
+ * «сочетание без Ctrl и Meta, которое печатает или правит текст, должно быть
+ * неактивно, пока фокус в поле ввода». `null` — привязка верна.
+ */
+export declare const validateBinding: (binding: {
+  readonly key: string;
+  readonly when: string | null;
+}, platforms: readonly Platform[]) => BindingProblem | null;
+//#endregion
+//#region packages/keybindings/src/user.d.ts
+export declare const KEYBINDING_LIMITS: {
+  readonly commands: 512;
+  readonly entriesPerCommand: 8;
+  readonly commandLength: 200;
+};
+/** Ключ команды в реестре окна: `app:<id>` или `extension:<extensionId>:<id>`. */
+export declare const COMMAND_KEY_PATTERN: RegExp;
+type UserIssueReason = 'syntax' | 'typing' | 'conflict' | 'limit' | 'duplicate';
+interface UserIssue {
+  readonly reason: UserIssueReason;
+  /** Путь к полю: `commands`, `commands.<ключ>`, `commands.<ключ>[0].key`. */
+  readonly field: string;
+  readonly command: string;
+  /** Вторая команда при `conflict`. */
+  readonly other?: string;
+  readonly message: string;
+}
+/**
+ * Хранимое значение → пользовательские привязки. Терпимо к мусору: команды с
+ * неверным ключом или не массивом и записи неверной формы отбрасываются,
+ * лишнее сверх лимитов обрезается; разбор клавиш и условий — дело карты и
+ * `validateUserKeybindings`.
+ */
+export declare const decodeUserKeybindings: (raw: unknown) => UserKeybindings;
+/**
+ * Проверка набора пользователя на платформе хоста: лимиты, форма ключей
+ * команд, клавиши и условия (`validateBinding`), повтор «клавиши + условие»
+ * в одной команде и пересечения привязок разных команд. Пустой список — набор
+ * верен.
+ */
+export declare const validateUserKeybindings: (user: UserKeybindings, platform: Platform) => UserIssue[];
+//#endregion
+export type { Binding, BindingDefinition, BindingIssue, BindingProblem, BindingSource, Candidate, Chord, Conflict, ContextLookup, KeyEventLike, Keymap, KeymapInput, Keystroke, Platform, Resolution, SpokenId, SyntaxReason, UserBindingEntry, UserIssue, UserIssueReason, UserKeybindings, WhenExpr, WhenReason };