@vui-rs/core 0.1.0

package/dist/keys.d.ts

@@ -0,0 +1,76 @@
+//#region src/keys.d.ts
+interface KeyEvent {
+  type: 'key';
+  /** Lowercase name: a printable (`"a"`, `"世"`) or a named key (`"enter"`, `"up"`). */
+  name: string;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+  /** The exact source bytes (as a string) this event was parsed from. */
+  raw: string;
+}
+interface PasteEvent {
+  type: 'paste';
+  text: string;
+}
+type MouseButton = 'left' | 'middle' | 'right' | 'wheelUp' | 'wheelDown';
+interface MouseEvent {
+  type: 'mouse';
+  kind: 'down' | 'up' | 'move' | 'drag' | 'wheel';
+  button: MouseButton | null;
+  x: number;
+  y: number;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+  raw: string;
+}
+type InputEvent = KeyEvent | PasteEvent | MouseEvent;
+/** Parse a chunk of terminal input into discrete key/paste events (stateless). */
+declare function parseKeys(data: string | Uint8Array): InputEvent[];
+interface KeyDecoder {
+  /** Feed a chunk; returns the events decodable so far. Buffers a partial tail. */
+  feed(data: string | Uint8Array): InputEvent[];
+  /**
+   * Force-parse the buffered partial tail (best-effort: a lone ESC becomes a bare
+   * Escape) and clear it. Call on an idle/escape timeout so a standalone Escape
+   * keypress — indistinguishable from the start of a CSI/SS3 sequence until more
+   * bytes arrive — isn't held until the next key. No-op when nothing is pending.
+   */
+  flush(): InputEvent[];
+  /** The currently-buffered partial tail (empty when fully drained). */
+  pending(): string;
+}
+/**
+ * Stateful decoder for live input: it carries a partial trailing escape/paste
+ * across chunks, so a sequence (or a large paste) split over multiple stdin reads
+ * still parses correctly. One decoder per input stream.
+ */
+declare function createKeyDecoder(): KeyDecoder;
+/**
+ * Test whether an event matches a key spec like `"ctrl+c"`, `"shift+tab"`,
+ * `"enter"`. Modifiers are order-insensitive; `super` is an alias for `meta`.
+ */
+declare function matchesKey(ev: InputEvent, spec: string): boolean;
+/** Tiny helper for building key specs: `Key.ctrl("c")`, `Key.enter`. */
+declare const Key: {
+  readonly ctrl: (k: string) => string;
+  readonly alt: (k: string) => string;
+  readonly shift: (k: string) => string;
+  readonly enter: "enter";
+  readonly tab: "tab";
+  readonly escape: "escape";
+  readonly backspace: "backspace";
+  readonly delete: "delete";
+  readonly up: "up";
+  readonly down: "down";
+  readonly left: "left";
+  readonly right: "right";
+  readonly home: "home";
+  readonly end: "end";
+  readonly space: "space";
+};
+//#endregion
+export { InputEvent, Key, KeyDecoder, KeyEvent, MouseButton, MouseEvent, PasteEvent, createKeyDecoder, matchesKey, parseKeys };

package/dist/keys.js

@@ -0,0 +1,373 @@
+//#region src/keys.ts
+const decoder = new TextDecoder();
+const PASTE_START = "\x1B[200~";
+const PASTE_END = "\x1B[201~";
+const MOUSE_BUTTONS = [
+	"left",
+	"middle",
+	"right"
+];
+const ARROW_NAMES = {
+	A: "up",
+	B: "down",
+	C: "right",
+	D: "left",
+	H: "home",
+	F: "end"
+};
+const TILDE_NAMES = {
+	"1": "home",
+	"2": "insert",
+	"3": "delete",
+	"4": "end",
+	"5": "pageUp",
+	"6": "pageDown",
+	"7": "home",
+	"8": "end"
+};
+const SS3_NAMES = {
+	...ARROW_NAMES,
+	P: "f1",
+	Q: "f2",
+	R: "f3",
+	S: "f4"
+};
+function key(name, opts = {}) {
+	return {
+		type: "key",
+		name,
+		ctrl: !!opts.ctrl,
+		alt: !!opts.alt,
+		shift: !!opts.shift,
+		meta: !!opts.meta,
+		raw: opts.raw ?? name
+	};
+}
+/** Decode a CSI modifier param (`m` in `1;m`) into modifier flags. */
+function decodeMod(param) {
+	const m = param ? Number.parseInt(param, 10) - 1 : 0;
+	return {
+		shift: !!(m & 1),
+		alt: !!(m & 2),
+		ctrl: !!(m & 4),
+		meta: !!(m & 8)
+	};
+}
+/**
+* Kitty keyboard protocol functional keycodes that map to a named key. The
+* protocol reports most printable keys by their Unicode codepoint (handled
+* below) and reserves these specific codepoints for named keys. Arrows, Home/
+* End, etc. keep their legacy `CSI letter`/`CSI ~` encodings even in Kitty mode,
+* so they continue through the existing decoder and aren't listed here.
+*/
+const KITTY_NAMED = {
+	13: "enter",
+	27: "escape",
+	9: "tab",
+	127: "backspace",
+	32: "space"
+};
+/**
+* Decode a Kitty modifier+event field (`mods` or `mods:event-type`). The modifier
+* bitfield is value-minus-1; bit layout: shift1 alt2 ctrl4 super8 hyper16 meta32.
+* `super`/`meta` both fold to our `meta` flag. Event type: 1 press, 2 repeat, 3
+* release (default 1 when absent).
+*/
+function decodeKittyMod(param) {
+	const [modStr, evStr] = (param ?? "").split(":");
+	const m = modStr ? Number.parseInt(modStr, 10) - 1 : 0;
+	const eventType = evStr ? Number.parseInt(evStr, 10) : 1;
+	return {
+		mods: {
+			shift: !!(m & 1),
+			alt: !!(m & 2),
+			ctrl: !!(m & 4),
+			meta: !!(m & 8) || !!(m & 32)
+		},
+		eventType
+	};
+}
+/**
+* Decode a Kitty keyboard `CSI <code>[:alt:base] ; <mods>[:event] u` sequence into
+* a KeyEvent. Key releases (event type 3) are dropped in v0; repeats (2) fire as a
+* normal press. Malformed/unmapped control keycodes are consumed silently.
+*/
+function parseCsiU(params, raw, consumed, out) {
+	const parts = params.split(";");
+	const keycode = Number.parseInt(parts[0].split(":")[0] ?? "", 10);
+	if (!Number.isFinite(keycode)) return consumed;
+	const { mods, eventType } = decodeKittyMod(parts[1]);
+	if (eventType === 3) return consumed;
+	let name = KITTY_NAMED[keycode];
+	if (name === void 0) if (keycode >= 32 && keycode !== 127) name = String.fromCodePoint(keycode);
+	else return consumed;
+	out.push(key(name, {
+		...mods,
+		raw
+	}));
+	return consumed;
+}
+function newMouseState() {
+	return { buttons: /* @__PURE__ */ new Set() };
+}
+function stepOne(s, i, out, mouse) {
+	const code = s.charCodeAt(i);
+	if (code === 27) {
+		const r = parseEscape(s, i, out, mouse);
+		if (r !== 0) return r;
+		out.push(key("escape", { raw: "\x1B" }));
+		return 1;
+	}
+	if (code === 13 || code === 10) out.push(key("enter", { raw: s[i] }));
+	else if (code === 9) out.push(key("tab", { raw: s[i] }));
+	else if (code === 127 || code === 8) out.push(key("backspace", { raw: s[i] }));
+	else if (code === 0) out.push(key("space", {
+		ctrl: true,
+		raw: s[i]
+	}));
+	else if (code >= 1 && code <= 26) out.push(key(String.fromCharCode(code + 96), {
+		ctrl: true,
+		raw: s[i]
+	}));
+	else if (code >= 28 && code <= 31) {} else {
+		const ch = String.fromCodePoint(s.codePointAt(i));
+		out.push(key(ch, {
+			raw: ch,
+			shift: ch.length === 1 && ch >= "A" && ch <= "Z"
+		}));
+		return ch.length;
+	}
+	return 1;
+}
+/** Parse a chunk of terminal input into discrete key/paste events (stateless). */
+function parseKeys(data) {
+	const s = typeof data === "string" ? data : decoder.decode(data);
+	const events = [];
+	const mouse = newMouseState();
+	let i = 0;
+	while (i < s.length) {
+		const consumed = stepOne(s, i, events, mouse);
+		if (consumed === -1) {
+			events.push(key("escape", { raw: "\x1B" }));
+			i += 1;
+		} else i += consumed;
+	}
+	return events;
+}
+/** A bare partial CSI/SS3 (no terminator) buffered this long is treated as stuck
+*  and flushed, so a malformed stream can't grow the pending buffer unbounded. A
+*  bracketed paste (identified by its start marker) is exempt — pastes are large
+*  by nature and must buffer until their end marker. */
+const MAX_PENDING = 64;
+/**
+* Stateful decoder for live input: it carries a partial trailing escape/paste
+* across chunks, so a sequence (or a large paste) split over multiple stdin reads
+* still parses correctly. One decoder per input stream.
+*/
+function createKeyDecoder() {
+	let pending = "";
+	const mouse = newMouseState();
+	return {
+		feed(data) {
+			const s = pending + (typeof data === "string" ? data : decoder.decode(data));
+			const events = [];
+			let i = 0;
+			while (i < s.length) {
+				const consumed = stepOne(s, i, events, mouse);
+				if (consumed === -1) break;
+				i += consumed;
+			}
+			pending = s.slice(i);
+			if (pending.length > MAX_PENDING && !pending.startsWith(PASTE_START)) {
+				for (const ev of parseKeys(pending)) events.push(ev);
+				pending = "";
+			}
+			return events;
+		},
+		flush() {
+			if (pending === "" || pending.startsWith(PASTE_START)) return [];
+			const events = parseKeys(pending);
+			pending = "";
+			return events;
+		},
+		pending() {
+			return pending;
+		}
+	};
+}
+/**
+* Parse an escape sequence starting at `i`. Returns bytes consumed, `0` for a
+* bare/unrecognised ESC (caller emits Escape), or `-1` for a truncated sequence
+* that needs more input.
+*/
+function parseEscape(s, i, out, mouse) {
+	const next = s[i + 1];
+	if (next === void 0) return -1;
+	if (next === "[") return parseCSI(s, i, out, mouse);
+	if (next === "O") return parseSS3(s, i, out);
+	const code = s.charCodeAt(i + 1);
+	if (code === 127 || code === 8) {
+		out.push(key("backspace", {
+			alt: true,
+			raw: s.slice(i, i + 2)
+		}));
+		return 2;
+	}
+	if (code >= 32) {
+		const ch = String.fromCodePoint(s.codePointAt(i + 1));
+		out.push(key(ch, {
+			alt: true,
+			raw: "\x1B" + ch
+		}));
+		return 1 + ch.length;
+	}
+	return 0;
+}
+function parseCSI(s, i, out, mouse) {
+	if (s[i + 2] === "<") return parseSgrMouse(s, i, out, mouse);
+	if (s[i + 2] === "M") return parseX10Mouse(s, i, out, mouse);
+	let j = i + 2;
+	let params = "";
+	while (j < s.length && (s[j] === ";" || s[j] === ":" || s[j] >= "0" && s[j] <= "9")) {
+		params += s[j];
+		j += 1;
+	}
+	const final = s[j];
+	if (final === void 0) return -1;
+	if (params === "200" && final === "~") {
+		const start = j + 1;
+		const end = s.indexOf(PASTE_END, start);
+		if (end === -1) return -1;
+		out.push({
+			type: "paste",
+			text: s.slice(start, end)
+		});
+		return end + 6 - i;
+	}
+	const raw = s.slice(i, j + 1);
+	const consumed = j + 1 - i;
+	if (final === "u") return parseCsiU(params, raw, consumed, out);
+	if (final === "Z") {
+		out.push(key("tab", {
+			shift: true,
+			raw
+		}));
+		return consumed;
+	}
+	const parts = params.split(";");
+	const mods = {
+		...decodeMod(parts[1]),
+		raw
+	};
+	if (ARROW_NAMES[final]) {
+		out.push(key(ARROW_NAMES[final], mods));
+		return consumed;
+	}
+	if (final === "~" && TILDE_NAMES[parts[0]]) {
+		out.push(key(TILDE_NAMES[parts[0]], mods));
+		return consumed;
+	}
+	return consumed;
+}
+function decodeMouseModifiers(code) {
+	return {
+		shift: !!(code & 4),
+		alt: !!(code & 8),
+		ctrl: !!(code & 16),
+		meta: false
+	};
+}
+function mouseButton(code) {
+	if (code & 64) return code & 1 ? "wheelDown" : "wheelUp";
+	return MOUSE_BUTTONS[code & 3] ?? null;
+}
+function pushMouse(out, mouse, code, x, y, final, raw) {
+	const wheel = !!(code & 64);
+	const motion = !!(code & 32);
+	const button = mouseButton(code);
+	const mods = decodeMouseModifiers(code);
+	let kind;
+	if (wheel) kind = "wheel";
+	else if (final === "m") kind = "up";
+	else if (motion) kind = mouse.buttons.size > 0 ? "drag" : "move";
+	else kind = "down";
+	if (kind === "down" && button) mouse.buttons.add(button);
+	if (kind === "up") if (button) mouse.buttons.delete(button);
+	else mouse.buttons.clear();
+	out.push({
+		type: "mouse",
+		kind,
+		button,
+		x,
+		y,
+		ctrl: !!mods.ctrl,
+		alt: !!mods.alt,
+		shift: !!mods.shift,
+		meta: false,
+		raw
+	});
+}
+function parseSgrMouse(s, i, out, mouse) {
+	let j = i + 3;
+	while (j < s.length && (s[j] === ";" || s[j] >= "0" && s[j] <= "9")) j += 1;
+	const final = s[j];
+	if (final === void 0) return -1;
+	if (final !== "M" && final !== "m") return j + 1 - i;
+	const raw = s.slice(i, j + 1);
+	const parts = s.slice(i + 3, j).split(";");
+	if (parts.length !== 3) return j + 1 - i;
+	const code = Number.parseInt(parts[0], 10);
+	const x = Number.parseInt(parts[1], 10) - 1;
+	const y = Number.parseInt(parts[2], 10) - 1;
+	if (!Number.isFinite(code) || !Number.isFinite(x) || !Number.isFinite(y) || x < 0 || y < 0) return j + 1 - i;
+	pushMouse(out, mouse, code, x, y, final, raw);
+	return j + 1 - i;
+}
+function parseX10Mouse(s, i, out, mouse) {
+	if (i + 5 >= s.length) return -1;
+	const raw = s.slice(i, i + 6);
+	const code = s.charCodeAt(i + 3) - 32;
+	const x = s.charCodeAt(i + 4) - 33;
+	const y = s.charCodeAt(i + 5) - 33;
+	if (x < 0 || y < 0) return 6;
+	pushMouse(out, mouse, code, x, y, code === 3 ? "m" : "M", raw);
+	return 6;
+}
+function parseSS3(s, i, out) {
+	const final = s[i + 2];
+	if (final === void 0) return -1;
+	const name = SS3_NAMES[final];
+	if (!name) return 0;
+	out.push(key(name, { raw: s.slice(i, i + 3) }));
+	return 3;
+}
+/**
+* Test whether an event matches a key spec like `"ctrl+c"`, `"shift+tab"`,
+* `"enter"`. Modifiers are order-insensitive; `super` is an alias for `meta`.
+*/
+function matchesKey(ev, spec) {
+	if (ev.type !== "key") return false;
+	const parts = spec.toLowerCase().split("+");
+	const base = parts.pop();
+	return ev.name.toLowerCase() === base && ev.ctrl === parts.includes("ctrl") && ev.alt === parts.includes("alt") && ev.shift === parts.includes("shift") && ev.meta === (parts.includes("meta") || parts.includes("super"));
+}
+/** Tiny helper for building key specs: `Key.ctrl("c")`, `Key.enter`. */
+const Key = {
+	ctrl: (k) => `ctrl+${k}`,
+	alt: (k) => `alt+${k}`,
+	shift: (k) => `shift+${k}`,
+	enter: "enter",
+	tab: "tab",
+	escape: "escape",
+	backspace: "backspace",
+	delete: "delete",
+	up: "up",
+	down: "down",
+	left: "left",
+	right: "right",
+	home: "home",
+	end: "end",
+	space: "space"
+};
+//#endregion
+export { Key, createKeyDecoder, matchesKey, parseKeys };

package/dist/named-colors.d.ts

@@ -0,0 +1,7 @@
+//#region src/named-colors.d.ts
+/** Parse a `#rgb`/`#rrggbb`/`#rrggbbaa` string to packed `0xRRGGBBAA`, or undefined. */
+declare function parseHex(value: string): number | undefined;
+/** Named color → packed `0xRRGGBBAA`. Built once from the shared JSON table. */
+declare const NAMED_COLORS: ReadonlyMap<string, number>;
+//#endregion
+export { NAMED_COLORS, parseHex };

package/dist/named-colors.js

@@ -0,0 +1,20 @@
+import color_names_default from "./color-names.js";
+//#region src/named-colors.ts
+/** Parse a `#rgb`/`#rrggbb`/`#rrggbbaa` string to packed `0xRRGGBBAA`, or undefined. */
+function parseHex(value) {
+	if (!value.startsWith("#")) return void 0;
+	let hex = value.slice(1);
+	if (hex.length === 3) hex = hex.split("").map((c) => c + c).join("");
+	if (hex.length === 6) hex += "ff";
+	if (hex.length !== 8) return void 0;
+	if (!/^[0-9a-fA-F]{8}$/.test(hex)) return void 0;
+	return Number.parseInt(hex, 16) >>> 0;
+}
+/** Named color → packed `0xRRGGBBAA`. Built once from the shared JSON table. */
+const NAMED_COLORS = new Map(Object.entries(color_names_default).map(([name, hex]) => {
+	const packed = parseHex(hex);
+	if (packed === void 0) throw new Error(`color-names.json: bad hex "${hex}" for "${name}"`);
+	return [name, packed];
+}));
+//#endregion
+export { NAMED_COLORS, parseHex };