@gitkraken/core-gitlens 0.5.109 → 0.5.111

package/src/utils/env/browser/base64.ts

@@ -14,7 +14,7 @@ export function base64(data: string | Uint8Array): string {
 	return globalThis.btoa(output);
 }
 
-export function fromBase64(s: string): Uint8Array {
+export function fromBase64(s: string): Uint8Array<ArrayBuffer> {
 	const decoded = globalThis.atob(s);
 
 	const len = decoded.length;

package/src/utils/env/node/base64.ts

@@ -4,7 +4,9 @@ export function base64(data: string | Uint8Array): string {
 	return Buffer.from(data).toString('base64');
 }
 
-export function fromBase64(s: string): Uint8Array {
+// Returns `Uint8Array<ArrayBuffer>` rather than a bare `Uint8Array` (which widens to `ArrayBufferLike` and
+// admits `SharedArrayBuffer`) so the result stays assignable to `BufferSource` — what Web Crypto accepts.
+export function fromBase64(s: string): Uint8Array<ArrayBuffer> {
 	return Buffer.from(s, 'base64');
 }
 

package/src/utils/keys/chord.ts

@@ -0,0 +1,184 @@
+/** Structural subset of a keyboard event; lets this module stay DOM-free. */
+export type KeyEventLike = {
+	key: string;
+	code: string;
+	ctrlKey: boolean;
+	altKey: boolean;
+	shiftKey: boolean;
+	metaKey: boolean;
+};
+
+export type ChordModifier = 'mod' | 'ctrl' | 'alt' | 'shift' | 'meta';
+
+/** A single parsed key combination, ready to match against key events. */
+export type Chord = {
+	/** The original token, e.g. `'ArrowUp'`, `'c'`, `'KeyM'`. */
+	token: string;
+	/** Whether the token is matched against `event.code` (layout-independent) or `event.key`. */
+	matchOn: 'key' | 'code';
+	ctrl: boolean;
+	alt: boolean;
+	meta: boolean;
+	/**
+	 * `true`/`false` when shift is a declared part of the chord; `'implicit'` when the token is a
+	 * single printable character whose shifted form already encodes the shift state (e.g. `'?'`),
+	 * so `event.shiftKey` is ignored at match time.
+	 */
+	shift: boolean | 'implicit';
+};
+
+const codeTokenPattern = /^(?:Key[A-Z]|Digit[0-9])$/;
+
+const readableTokens = new Map<string, string>([
+	['ArrowUp', '↑'],
+	['ArrowDown', '↓'],
+	['ArrowLeft', '←'],
+	['ArrowRight', '→'],
+	['Escape', 'Esc'],
+	[' ', 'Space'],
+	['PageUp', 'PgUp'],
+	['PageDown', 'PgDn'],
+]);
+
+/**
+ * Parses a `+`-separated key combination such as `'mod+c'` or `'alt+KeyM'` into a {@link Chord}.
+ * Throws on malformed input. `isMac` resolves the `'mod'` modifier (`meta` on mac, `ctrl` otherwise).
+ */
+export function parseChord(input: string, isMac: boolean): Chord {
+	if (!input) throw new Error(`Invalid key chord '${input}': empty input`);
+
+	const parts = input.split('+');
+
+	// A trailing/leading '+' (literal plus as the token) produces an empty part adjacent to a
+	// non-empty one; a lone '+' would split to ['', ''] and is handled by the empty-token check below.
+	if (parts.length > 1 && parts.at(-1) === '') {
+		throw new Error(`Invalid key chord '${input}': trailing '+'`);
+	}
+
+	const modifiers = parts.slice(0, -1);
+	const token = parts.at(-1)!;
+
+	if (token === '') throw new Error(`Invalid key chord '${input}': empty token`);
+
+	let mod = false;
+	let ctrl = false;
+	let alt = false;
+	let shift = false;
+	let meta = false;
+
+	for (const modifier of modifiers) {
+		switch (modifier) {
+			case 'mod':
+				if (mod) throw new Error(`Invalid key chord '${input}': duplicate modifier 'mod'`);
+
+				mod = true;
+				break;
+			case 'ctrl':
+				if (ctrl) throw new Error(`Invalid key chord '${input}': duplicate modifier 'ctrl'`);
+
+				ctrl = true;
+				break;
+			case 'alt':
+				if (alt) throw new Error(`Invalid key chord '${input}': duplicate modifier 'alt'`);
+
+				alt = true;
+				break;
+			case 'shift':
+				if (shift) throw new Error(`Invalid key chord '${input}': duplicate modifier 'shift'`);
+
+				shift = true;
+				break;
+			case 'meta':
+				if (meta) throw new Error(`Invalid key chord '${input}': duplicate modifier 'meta'`);
+
+				meta = true;
+				break;
+			default:
+				throw new Error(`Invalid key chord '${input}': unknown modifier '${modifier}'`);
+		}
+	}
+
+	if (mod && ctrl) throw new Error(`Invalid key chord '${input}': 'mod' conflicts with explicit 'ctrl'`);
+
+	if (mod && meta) throw new Error(`Invalid key chord '${input}': 'mod' conflicts with explicit 'meta'`);
+
+	if (mod) {
+		if (isMac) {
+			meta = true;
+		} else {
+			ctrl = true;
+		}
+	}
+
+	const matchOn: Chord['matchOn'] = codeTokenPattern.test(token) ? 'code' : 'key';
+
+	let resolvedShift: Chord['shift'];
+	if (matchOn === 'code') {
+		resolvedShift = shift;
+	} else if ([...token].length === 1) {
+		if (shift) {
+			throw new Error(`Invalid key chord '${input}': 'shift' cannot combine with a single-character token`);
+		}
+
+		resolvedShift = 'implicit';
+	} else {
+		resolvedShift = shift;
+	}
+
+	return { token: token, matchOn: matchOn, ctrl: ctrl, alt: alt, meta: meta, shift: resolvedShift };
+}
+
+/** Tests whether a key event matches a parsed chord — all declared modifiers must match exactly. */
+export function matchesChord(chord: Chord, e: KeyEventLike): boolean {
+	if (chord.ctrl !== e.ctrlKey) return false;
+	if (chord.alt !== e.altKey) return false;
+	if (chord.meta !== e.metaKey) return false;
+
+	if (chord.shift !== 'implicit' && chord.shift !== e.shiftKey) return false;
+
+	return chord.matchOn === 'code' ? e.code === chord.token : e.key === chord.token;
+}
+
+export type ChordSymbols = { ctrl: string; alt: string; shift: string; meta: string };
+
+/** One display chip: a modifier (renderers style these differently) or the chord's own key. */
+export type ChordPart = { text: string; kind: 'mod' | 'key' };
+
+/**
+ * Formats a chord into an ordered list of typed display chips (ctrl → alt → shift → meta → token).
+ * An implicit-shift chord contributes no shift chip — its token already spells the shifted form.
+ */
+export function formatChordParts(chord: Chord, symbols: ChordSymbols): ChordPart[] {
+	const parts: ChordPart[] = [];
+
+	if (chord.ctrl) {
+		parts.push({ text: symbols.ctrl, kind: 'mod' });
+	}
+
+	if (chord.alt) {
+		parts.push({ text: symbols.alt, kind: 'mod' });
+	}
+
+	if (chord.shift === true) {
+		parts.push({ text: symbols.shift, kind: 'mod' });
+	}
+
+	if (chord.meta) {
+		parts.push({ text: symbols.meta, kind: 'mod' });
+	}
+
+	parts.push({ text: formatToken(chord), kind: 'key' });
+
+	return parts;
+}
+
+/** Formats a chord into an ordered list of display chips (ctrl → alt → shift → meta → token). */
+export function formatChord(chord: Chord, symbols: ChordSymbols): string[] {
+	return formatChordParts(chord, symbols).map(part => part.text);
+}
+
+function formatToken(chord: Chord): string {
+	if (chord.matchOn === 'code') return chord.token.replace(/^(?:Key|Digit)/, '');
+
+	return readableTokens.get(chord.token) ?? chord.token;
+}

package/src/utils/keys/keybinding.ts

@@ -0,0 +1,116 @@
+import type { Chord, KeyEventLike } from './chord.js';
+import { matchesChord, parseChord } from './chord.js';
+
+/**
+ * One item in a sheet row's key rail or subline, in a mini-grammar the renderer resolves:
+ * - a bare chord (`'mod+KeyC'`, `'ArrowUp'`) — parsed and formatted into chips
+ * - `'raw:X'` — literal `X` in a key chip
+ * - `'mod:X'` — literal `X` in a modifier chip
+ * - `'text:X'` — literal `X` as plain inline text, verbatim (leading/trailing spaces included)
+ * - `'sep:X'` — literal `X` as a muted separator glyph
+ */
+export type SheetDisplayEntry = string;
+
+export type SheetEntry = {
+	group: string;
+	label: string;
+	order?: number;
+	keysOverride?: readonly SheetDisplayEntry[];
+	/** Second line rendered under the label — same display grammar as `keysOverride`. */
+	subline?: readonly SheetDisplayEntry[];
+};
+
+export type KeyBindingDescriptor<TScope extends string, TEvent extends KeyEventLike = KeyEventLike> = {
+	keys: readonly string[];
+	scope: TScope;
+	order?: number;
+	when?: readonly ((e: TEvent) => boolean)[];
+	run: (e: TEvent) => boolean;
+	sheet: SheetEntry | 'hidden';
+};
+
+/** A registered binding: descriptor + parsed chords (parse once at registration). */
+export type KeyBinding<TScope extends string, TEvent extends KeyEventLike = KeyEventLike> = KeyBindingDescriptor<
+	TScope,
+	TEvent
+> & { chords: readonly Chord[] };
+
+export type OverlayEntry = {
+	id: string;
+	/**
+	 * Close the surface. Returns false to decline (surface decides it wasn't actually open/closable),
+	 * letting resolution continue to the next overlay down, then the focus chain.
+	 */
+	onClose: () => boolean;
+};
+
+/**
+ * Pure candidate selection: which bindings could handle this event, in resolution order —
+ * scope chain innermost→outermost (chain[0] = innermost), `order` ascending within a scope
+ * (undefined order sorts last), registration (array) order as the final tiebreak. Does NOT
+ * evaluate `when` guards or call `run` — the dispatcher does that so scope guards can sit between.
+ */
+export function resolveKeydown<TScope extends string, TEvent extends KeyEventLike>(
+	bindings: readonly KeyBinding<TScope, TEvent>[],
+	scopeChain: readonly TScope[],
+	e: KeyEventLike,
+): KeyBinding<TScope, TEvent>[] {
+	const matches: { binding: KeyBinding<TScope, TEvent>; scopeIndex: number; registrationIndex: number }[] = [];
+
+	for (let i = 0; i < bindings.length; i++) {
+		const binding = bindings[i];
+
+		const scopeIndex = scopeChain.indexOf(binding.scope);
+		if (scopeIndex === -1) continue;
+
+		if (!binding.chords.some(chord => matchesChord(chord, e))) continue;
+
+		matches.push({ binding: binding, scopeIndex: scopeIndex, registrationIndex: i });
+	}
+
+	matches.sort((a, b) => {
+		if (a.scopeIndex !== b.scopeIndex) return a.scopeIndex - b.scopeIndex;
+
+		const orderA = a.binding.order;
+		const orderB = b.binding.order;
+		if (orderA !== orderB) {
+			if (orderA == null) return 1;
+			if (orderB == null) return -1;
+
+			return orderA - orderB;
+		}
+
+		return a.registrationIndex - b.registrationIndex;
+	});
+
+	return matches.map(m => m.binding);
+}
+
+/**
+ * Pure overlay resolution for a close request (Esc): returns the entries to try, top of stack
+ * first. The dispatcher calls onClose top-down until one returns true.
+ */
+export function resolveOverlayClose(stack: readonly OverlayEntry[]): OverlayEntry[] {
+	return [...stack].reverse();
+}
+
+/** Parses a descriptor's keys into chords, throwing on the first malformed key. */
+export function registerBinding<TScope extends string, TEvent extends KeyEventLike = KeyEventLike>(
+	descriptor: KeyBindingDescriptor<TScope, TEvent>,
+	isMac: boolean,
+): KeyBinding<TScope, TEvent> {
+	const chords: Chord[] = [];
+
+	for (const key of descriptor.keys) {
+		try {
+			chords.push(parseChord(key, isMac));
+		} catch (ex) {
+			const reason = ex instanceof Error ? ex.message : String(ex);
+			throw new Error(`Invalid key binding for scope '${descriptor.scope}', key '${key}': ${reason}`, {
+				cause: ex,
+			});
+		}
+	}
+
+	return { ...descriptor, chords: chords };
+}

package/src/utils/path.ts

@@ -93,6 +93,20 @@ export function stripFolderGlob(path: string): string {
 	return isFolderGlob(path) ? path.slice(0, -2) : path;
 }
 
+/**
+ * Trims the trailing slash git puts on an untracked directory that is itself a repository
+ * (`nested-repo/`), which it reports as one entry because it can't recurse past the embedded
+ * repository boundary. Status is fetched with `-u` (= `all`), so ordinary untracked directories are
+ * recursed into and a trailing slash identifies the nested-repository case unambiguously.
+ *
+ * Deliberately not {@link normalizePath}, which also rewrites backslashes: git paths always use `/`,
+ * so a backslash here is a literal character in a (POSIX-legal) filename, and rewriting it would
+ * split the name across folders wherever the result is used to derive a display name or a tree path.
+ */
+export function trimTrailingSlash(path: string): string {
+	return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
 export function getBestPath(pathOrUri: string): string {
 	if (!hasScheme(pathOrUri)) return normalizePath(pathOrUri);