@f5xc-salesdemos/pi-tui 18.8.2 → 18.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/pi-tui",
-	"version": "18.8.2",
+	"version": "18.9.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@f5xc-salesdemos/pi-natives": "18.8.2",
-		"@f5xc-salesdemos/pi-utils": "18.8.2",
+		"@f5xc-salesdemos/pi-natives": "18.9.0",
+		"@f5xc-salesdemos/pi-utils": "18.9.0",
 		"marked": "^17.0"
 	},
 	"devDependencies": {

package/src/chord-dispatcher.ts

@@ -0,0 +1,90 @@
+import type { ChordBinding } from "./chord-parser";
+import type { KeyId } from "./keys";
+
+export type ChordResult =
+	| { kind: "dispatched"; action: string }
+	| { kind: "pending"; leader: KeyId }
+	| { kind: "passthrough" }
+	| { kind: "abandoned" };
+
+export interface ChordDispatcherCallbacks {
+	onPending?: (leader: KeyId) => void;
+	onCleared?: () => void;
+}
+
+interface PendingState {
+	leader: KeyId;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Two-key chord state machine. Stateless across keystrokes except for one
+ * optional "pending leader" slot + its timeout timer. Consumers feed KeyIds
+ * via feedKey() and act on the returned ChordResult.
+ */
+export class ChordDispatcher {
+	readonly #bindings: ChordBinding[];
+	readonly #timeoutMs: number;
+	readonly #callbacks: ChordDispatcherCallbacks;
+	#pending: PendingState | null = null;
+
+	constructor(bindings: ChordBinding[], timeoutMs: number, callbacks: ChordDispatcherCallbacks = {}) {
+		this.#bindings = bindings;
+		this.#timeoutMs = timeoutMs;
+		this.#callbacks = callbacks;
+	}
+
+	feedKey(key: KeyId): ChordResult {
+		// Phase 1: pending chord is active — interpret this key as the 2nd stroke.
+		if (this.#pending) {
+			const match = this.#bindings.find(
+				b => b.sequence.length === 2 && b.sequence[0] === this.#pending!.leader && b.sequence[1] === key,
+			);
+			this.#clearPending();
+			if (match) return { kind: "dispatched", action: match.action };
+			return { kind: "abandoned" };
+		}
+
+		// Phase 2: no pending chord.
+		// Single-stroke match wins first.
+		for (const b of this.#bindings) {
+			if (b.sequence.length === 1 && b.sequence[0] === key) {
+				return { kind: "dispatched", action: b.action };
+			}
+		}
+		// Chord leader?
+		const isLeader = this.#bindings.some(b => b.sequence.length === 2 && b.sequence[0] === key);
+		if (isLeader) {
+			this.#setPending(key);
+			return { kind: "pending", leader: key };
+		}
+		return { kind: "passthrough" };
+	}
+
+	#setPending(leader: KeyId): void {
+		const timer = setTimeout(() => this.#timeoutClear(), this.#timeoutMs);
+		this.#pending = { leader, timer };
+		this.#callbacks.onPending?.(leader);
+	}
+
+	#clearPending(): void {
+		if (!this.#pending) return;
+		clearTimeout(this.#pending.timer);
+		this.#pending = null;
+		this.#callbacks.onCleared?.();
+	}
+
+	#timeoutClear(): void {
+		// Timer fired; timer handle consumed by runtime.
+		if (!this.#pending) return;
+		this.#pending = null;
+		this.#callbacks.onCleared?.();
+	}
+
+	dispose(): void {
+		if (this.#pending) {
+			clearTimeout(this.#pending.timer);
+			this.#pending = null;
+		}
+	}
+}

package/src/chord-parser.ts

@@ -0,0 +1,66 @@
+import type { KeyId } from "./keys";
+
+export interface ParsedBinding {
+	sequence: KeyId[];
+}
+
+export interface BindingParseError {
+	readonly message: string;
+	readonly input: string;
+}
+
+export type ParseResult = { ok: true; sequence: KeyId[] } | { ok: false; error: BindingParseError };
+
+/**
+ * Parse a binding string into a keystroke sequence.
+ *
+ * - Whitespace separates keystrokes in a chord.
+ * - One keystroke = single-stroke binding; two keystrokes = chord.
+ * - v1 rejects 3+ keystrokes.
+ * - Individual keystroke validation (known key names + modifier combos) is
+ *   deferred to KeyId at type check time and at runtime via parseKey on input.
+ */
+export function parseBinding(input: string): ParseResult {
+	const trimmed = input.trim();
+	if (trimmed.length === 0) {
+		return { ok: false, error: { message: "empty binding", input } };
+	}
+	const tokens = trimmed.split(/\s+/);
+	if (tokens.length > 2) {
+		return {
+			ok: false,
+			error: {
+				message: `chord bindings support at most 2 keystrokes (got ${tokens.length})`,
+				input,
+			},
+		};
+	}
+	return { ok: true, sequence: tokens as KeyId[] };
+}
+
+export interface ChordBinding {
+	action: string;
+	sequence: KeyId[];
+}
+
+export type BindingsInput = Record<string, string | string[]>;
+
+export type ParseBindingsResult = { ok: true; bindings: ChordBinding[] } | { ok: false; error: BindingParseError };
+
+/**
+ * Parse a map of action → binding string(s) into a flat list of ChordBinding.
+ * Array values expand into multiple ChordBindings for the same action.
+ * Stops at the first parse error.
+ */
+export function parseBindings(input: BindingsInput): ParseBindingsResult {
+	const bindings: ChordBinding[] = [];
+	for (const [action, value] of Object.entries(input)) {
+		const list = Array.isArray(value) ? value : [value];
+		for (const str of list) {
+			const parsed = parseBinding(str);
+			if (!parsed.ok) return parsed;
+			bindings.push({ action, sequence: parsed.sequence });
+		}
+	}
+	return { ok: true, bindings };
+}

package/src/index.ts

@@ -2,6 +2,23 @@
 
 // Autocomplete support
 export * from "./autocomplete";
+// Chord dispatcher
+export {
+	ChordDispatcher,
+	type ChordDispatcherCallbacks,
+	type ChordResult,
+} from "./chord-dispatcher";
+// Chord parser
+export {
+	type BindingParseError,
+	type BindingsInput,
+	type ChordBinding,
+	type ParseBindingsResult,
+	type ParsedBinding,
+	type ParseResult,
+	parseBinding,
+	parseBindings,
+} from "./chord-parser";
 // Components
 export * from "./components/box";
 export * from "./components/cancellable-loader";

package/src/keybindings.ts

@@ -1,3 +1,4 @@
+import { type ChordBinding, parseBinding } from "./chord-parser";
 import { type KeyId, matchesKey, parseKey } from "./keys";
 
 /**
@@ -46,13 +47,20 @@ export type Keybinding = keyof Keybindings;
 // Re-export KeyId from keys.ts
 export type { KeyId };
 
+/**
+ * Binding string accepted by the config layer. Single-stroke values are
+ * KeyId (strict template-literal union); chord-syntax values (e.g.
+ * "ctrl+x b") are plain strings validated at runtime by parseBinding.
+ */
+export type BindingString = KeyId | string;
+
 export interface KeybindingDefinition {
-	defaultKeys: KeyId | KeyId[];
+	defaultKeys: BindingString | BindingString[];
 	description?: string;
 }
 
 export type KeybindingDefinitions = Record<string, KeybindingDefinition>;
-export type KeybindingsConfig = Record<string, KeyId | KeyId[] | undefined>;
+export type KeybindingsConfig = Record<string, BindingString | BindingString[] | undefined>;
 
 export const TUI_KEYBINDINGS = {
 	"tui.editor.cursorUp": { defaultKeys: "up", description: "Move cursor up" },
@@ -164,9 +172,9 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 	"~",
 ]);
 
-const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
+const normalizeKeyId = (key: BindingString): KeyId => key.toLowerCase() as KeyId;
 
-function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
+function normalizeKeys(keys: BindingString | BindingString[] | undefined): KeyId[] {
 	if (keys === undefined) return [];
 	const keyList = Array.isArray(keys) ? keys : [keys];
 	const seen = new Set<KeyId>();
@@ -263,6 +271,59 @@ export class KeybindingsManager {
 		}
 		return resolved;
 	}
+
+	/**
+	 * Return all bindings (standalone + chord) with their action names, with
+	 * user overrides already applied (same rules as getResolvedBindings).
+	 */
+	getChordBindings(): ChordBinding[] {
+		const result: ChordBinding[] = [];
+		for (const [action, keys] of this.#keysById) {
+			for (const key of keys) {
+				const parsed = parseBinding(key);
+				if (!parsed.ok) continue;
+				result.push({ action, sequence: parsed.sequence });
+			}
+		}
+		return result;
+	}
+
+	/**
+	 * Return conflicts where a key is used BOTH as a chord leader AND as a
+	 * standalone binding for some other action. Consumers (InputController)
+	 * should refuse to initialize the dispatcher if any are reported.
+	 */
+	getChordConflicts(): Array<{
+		key: KeyId;
+		standaloneActions: string[];
+		chordActions: string[];
+	}> {
+		const standaloneByKey = new Map<KeyId, Set<string>>();
+		const leaderByKey = new Map<KeyId, Set<string>>();
+		for (const binding of this.getChordBindings()) {
+			const [first, second] = binding.sequence;
+			if (second === undefined) {
+				const set = standaloneByKey.get(first!) ?? new Set<string>();
+				set.add(binding.action);
+				standaloneByKey.set(first!, set);
+			} else {
+				const set = leaderByKey.get(first!) ?? new Set<string>();
+				set.add(binding.action);
+				leaderByKey.set(first!, set);
+			}
+		}
+		const conflicts: Array<{ key: KeyId; standaloneActions: string[]; chordActions: string[] }> = [];
+		for (const [key, leaders] of leaderByKey) {
+			const standalones = standaloneByKey.get(key);
+			if (!standalones || standalones.size === 0) continue;
+			conflicts.push({
+				key,
+				standaloneActions: [...standalones].sort(),
+				chordActions: [...leaders].sort(),
+			});
+		}
+		return conflicts;
+	}
 }
 
 let globalKeybindings: KeybindingsManager | null = null;