tinky-mouse 0.1.0

package/lib/utils/mouse.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMouseEventName = getMouseEventName;
+exports.parseSGRMouseEvent = parseSGRMouseEvent;
+exports.parseX11MouseEvent = parseX11MouseEvent;
+exports.parseMouseEvent = parseMouseEvent;
+exports.isIncompleteMouseSequence = isIncompleteMouseSequence;
+var sequences_js_1 = require("./sequences.js");
+/**
+ * Derives the `MouseEventName` from the SGR button code and release state.
+ *
+ * @param buttonCode - The numerical code from the SGR sequence.
+ * @param isRelease - Whether the event is a release event (last char is 'm').
+ * @returns The `MouseEventName` or `null` if unknown.
+ */
+function getMouseEventName(buttonCode, isRelease) {
+    var isMove = (buttonCode & 32) !== 0;
+    if (buttonCode === 66) {
+        return "scroll-left";
+    }
+    else if (buttonCode === 67) {
+        return "scroll-right";
+    }
+    else if ((buttonCode & 64) === 64) {
+        if ((buttonCode & 1) === 0) {
+            return "scroll-up";
+        }
+        else {
+            return "scroll-down";
+        }
+    }
+    else if (isMove) {
+        return "move";
+    }
+    else {
+        var button = buttonCode & 3;
+        var type = isRelease ? "release" : "press";
+        switch (button) {
+            case 0:
+                return "left-".concat(type);
+            case 1:
+                return "middle-".concat(type);
+            case 2:
+                return "right-".concat(type);
+            default:
+                return null;
+        }
+    }
+}
+function getButtonFromCode(code) {
+    var button = code & 3;
+    switch (button) {
+        case 0:
+            return "left";
+        case 1:
+            return "middle";
+        case 2:
+            return "right";
+        default:
+            return "none";
+    }
+}
+/**
+ * Parses an SGR (1006) mouse sequence.
+ *
+ * @param buffer - The input string containing the sequence.
+ * @returns An object containing the parsed event and the length of the matched sequence, or `null` if not an SGR sequence.
+ *
+ * @example
+ * ```ts
+ * parseSGRMouseEvent("\x1b[<0;10;10M"); // Left press at 10,10
+ * ```
+ */
+function parseSGRMouseEvent(buffer) {
+    var match = buffer.match(sequences_js_1.SGR_MOUSE_REGEX);
+    if (match) {
+        var buttonCode = parseInt(match[1], 10);
+        var col = parseInt(match[2], 10);
+        var row = parseInt(match[3], 10);
+        var action = match[4];
+        var isRelease = action === "m";
+        var shift = (buttonCode & 4) !== 0;
+        var meta = (buttonCode & 8) !== 0;
+        var ctrl = (buttonCode & 16) !== 0;
+        var name_1 = getMouseEventName(buttonCode, isRelease);
+        if (name_1) {
+            return {
+                event: {
+                    name: name_1,
+                    ctrl: ctrl,
+                    meta: meta,
+                    shift: shift,
+                    col: col,
+                    row: row,
+                    button: getButtonFromCode(buttonCode),
+                },
+                length: match[0].length,
+            };
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Parses an X11 mouse sequence.
+ *
+ * @param buffer - The input string containing the sequence.
+ * @returns An object containing the parsed event and the length of the matched sequence, or `null` if not an X11 sequence.
+ *
+ * @example
+ * ```ts
+ * parseX11MouseEvent("\x1b[M..."); // Parsed X11 event
+ * ```
+ */
+function parseX11MouseEvent(buffer) {
+    var match = buffer.match(sequences_js_1.X11_MOUSE_REGEX);
+    if (!match)
+        return null;
+    // The 3 bytes are in match[1]
+    var b = match[1].charCodeAt(0) - 32;
+    var col = match[1].charCodeAt(1) - 32;
+    var row = match[1].charCodeAt(2) - 32;
+    var shift = (b & 4) !== 0;
+    var meta = (b & 8) !== 0;
+    var ctrl = (b & 16) !== 0;
+    var isMove = (b & 32) !== 0;
+    var isWheel = (b & 64) !== 0;
+    var name = null;
+    if (isWheel) {
+        var button = b & 3;
+        switch (button) {
+            case 0:
+                name = "scroll-up";
+                break;
+            case 1:
+                name = "scroll-down";
+                break;
+            default:
+                break;
+        }
+    }
+    else if (isMove) {
+        name = "move";
+    }
+    else {
+        var button = b & 3;
+        if (button === 3) {
+            // X11 reports 'release' (3) for all button releases without specifying which one.
+            // We'll default to 'left-release' as a best-effort guess if we don't track state.
+            name = "left-release";
+        }
+        else {
+            switch (button) {
+                case 0:
+                    name = "left-press";
+                    break;
+                case 1:
+                    name = "middle-press";
+                    break;
+                case 2:
+                    name = "right-press";
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+    if (name) {
+        var button = getButtonFromCode(b);
+        if (name === "left-release" && button === "none") {
+            button = "left";
+        }
+        return {
+            event: {
+                name: name,
+                ctrl: ctrl,
+                meta: meta,
+                shift: shift,
+                col: col,
+                row: row,
+                button: button,
+            },
+            length: match[0].length,
+        };
+    }
+    return null;
+}
+/**
+ * Attempts to parse a mouse event from the buffer, trying both SGR and X11 formats.
+ *
+ * @param buffer - The input string.
+ * @returns The parsed event and length, or `null`.
+ */
+function parseMouseEvent(buffer) {
+    return parseSGRMouseEvent(buffer) || parseX11MouseEvent(buffer);
+}
+/**
+ * Checks if the buffer contains an incomplete mouse sequence.
+ * This is useful for knowing if we should wait for more data before processing.
+ *
+ * @param buffer - The input string.
+ * @returns `true` if the buffer looks like the start of a mouse sequence but is incomplete.
+ */
+function isIncompleteMouseSequence(buffer) {
+    if (!(0, sequences_js_1.couldBeMouseSequence)(buffer))
+        return false;
+    // If it matches a complete sequence, it's not incomplete.
+    if (parseMouseEvent(buffer))
+        return false;
+    if (buffer.startsWith(sequences_js_1.X11_EVENT_PREFIX)) {
+        // X11 needs exactly 3 bytes after prefix.
+        return buffer.length < sequences_js_1.X11_EVENT_PREFIX.length + 3;
+    }
+    if (buffer.startsWith(sequences_js_1.SGR_EVENT_PREFIX)) {
+        // SGR sequences end with 'm' or 'M'.
+        // If it doesn't have it yet, it's incomplete.
+        // Add a reasonable max length check to fail early on garbage.
+        return !/[mM]/.test(buffer) && buffer.length < 50;
+    }
+    // It's a prefix of the prefix (e.g. "ESC" or "ESC [")
+    return true;
+}

package/lib/utils/sequences.d.ts

@@ -0,0 +1,52 @@
+/** ESC character (ASCII 27). */
+export declare const ESC = "\u001B";
+/** Prefix for SGR (1006) mouse sequences. */
+export declare const SGR_EVENT_PREFIX = "\u001B[<";
+/** Prefix for X11 mouse sequences. */
+export declare const X11_EVENT_PREFIX = "\u001B[M";
+/** Regex to match a complete SGR mouse event sequence. */
+export declare const SGR_MOUSE_REGEX: RegExp;
+/** Regex to match a complete X11 mouse event sequence. */
+export declare const X11_MOUSE_REGEX: RegExp;
+/**
+ * Checks if the buffer starts with or is a prefix of an SGR mouse sequence.
+ *
+ * @param buffer - The input string buffer.
+ * @returns `true` if it could be an SGR sequence, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * couldBeSGRMouseSequence("\x1b[<"); // true
+ * couldBeSGRMouseSequence("\x1b[<0;0;0M"); // true
+ * couldBeSGRMouseSequence("hello"); // false
+ * ```
+ */
+export declare function couldBeSGRMouseSequence(buffer: string): boolean;
+/**
+ * Checks if the buffer starts with or is a prefix of any known mouse sequence (SGR or X11).
+ *
+ * @param buffer - The input string buffer.
+ * @returns `true` if it could be a mouse sequence, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * couldBeMouseSequence("\x1b[M"); // true
+ * couldBeMouseSequence("\x1b[<"); // true
+ * ```
+ */
+export declare function couldBeMouseSequence(buffer: string): boolean;
+/**
+ * Checks if the buffer *starts* with a complete mouse sequence.
+ * Returns the length of the sequence if matched, or 0 if not.
+ *
+ * @param buffer - The input string buffer.
+ * @returns The length of the sequence in bytes/characters, or 0 if no complete sequence is found at the start.
+ *
+ * @example
+ * ```ts
+ * getMouseSequenceLength("\x1b[<0;10;10M"); // Returns length of the sequence
+ * getMouseSequenceLength("\x1b[M   "); // Returns length of X11 sequence
+ * getMouseSequenceLength("not mouse"); // 0
+ * ```
+ */
+export declare function getMouseSequenceLength(buffer: string): number;

package/lib/utils/sequences.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X11_MOUSE_REGEX = exports.SGR_MOUSE_REGEX = exports.X11_EVENT_PREFIX = exports.SGR_EVENT_PREFIX = exports.ESC = void 0;
+exports.couldBeSGRMouseSequence = couldBeSGRMouseSequence;
+exports.couldBeMouseSequence = couldBeMouseSequence;
+exports.getMouseSequenceLength = getMouseSequenceLength;
+/* eslint-disable no-control-regex */
+/** ESC character (ASCII 27). */
+exports.ESC = "\u001B";
+/** Prefix for SGR (1006) mouse sequences. */
+exports.SGR_EVENT_PREFIX = "".concat(exports.ESC, "[<");
+/** Prefix for X11 mouse sequences. */
+exports.X11_EVENT_PREFIX = "".concat(exports.ESC, "[M");
+/** Regex to match a complete SGR mouse event sequence. */
+exports.SGR_MOUSE_REGEX = /^\x1b\[<(\d+);(\d+);(\d+)([mM])/; // SGR mouse events
+// X11 is ESC [ M followed by 3 bytes.
+/** Regex to match a complete X11 mouse event sequence. */
+exports.X11_MOUSE_REGEX = /^\x1b\[M([\s\S]{3})/;
+/**
+ * Checks if the buffer starts with or is a prefix of an SGR mouse sequence.
+ *
+ * @param buffer - The input string buffer.
+ * @returns `true` if it could be an SGR sequence, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * couldBeSGRMouseSequence("\x1b[<"); // true
+ * couldBeSGRMouseSequence("\x1b[<0;0;0M"); // true
+ * couldBeSGRMouseSequence("hello"); // false
+ * ```
+ */
+function couldBeSGRMouseSequence(buffer) {
+    if (buffer.length === 0)
+        return true;
+    // Check if buffer is a prefix of a mouse sequence starter
+    if (exports.SGR_EVENT_PREFIX.startsWith(buffer))
+        return true;
+    // Check if buffer is a mouse sequence prefix
+    if (buffer.startsWith(exports.SGR_EVENT_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * Checks if the buffer starts with or is a prefix of any known mouse sequence (SGR or X11).
+ *
+ * @param buffer - The input string buffer.
+ * @returns `true` if it could be a mouse sequence, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * couldBeMouseSequence("\x1b[M"); // true
+ * couldBeMouseSequence("\x1b[<"); // true
+ * ```
+ */
+function couldBeMouseSequence(buffer) {
+    if (buffer.length === 0)
+        return true;
+    // Check SGR prefix
+    if (exports.SGR_EVENT_PREFIX.startsWith(buffer) ||
+        buffer.startsWith(exports.SGR_EVENT_PREFIX))
+        return true;
+    // Check X11 prefix
+    if (exports.X11_EVENT_PREFIX.startsWith(buffer) ||
+        buffer.startsWith(exports.X11_EVENT_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * Checks if the buffer *starts* with a complete mouse sequence.
+ * Returns the length of the sequence if matched, or 0 if not.
+ *
+ * @param buffer - The input string buffer.
+ * @returns The length of the sequence in bytes/characters, or 0 if no complete sequence is found at the start.
+ *
+ * @example
+ * ```ts
+ * getMouseSequenceLength("\x1b[<0;10;10M"); // Returns length of the sequence
+ * getMouseSequenceLength("\x1b[M   "); // Returns length of X11 sequence
+ * getMouseSequenceLength("not mouse"); // 0
+ * ```
+ */
+function getMouseSequenceLength(buffer) {
+    var sgrMatch = buffer.match(exports.SGR_MOUSE_REGEX);
+    if (sgrMatch)
+        return sgrMatch[0].length;
+    var x11Match = buffer.match(exports.X11_MOUSE_REGEX);
+    if (x11Match)
+        return x11Match[0].length;
+    return 0;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "tinky-mouse",
+  "version": "0.1.0",
+  "description": "Mouse event handling for tinky applications",
+  "keywords": [
+    "tinky",
+    "mouse",
+    "event",
+    "input",
+    "terminal",
+    "interaction"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/tinky-mouse#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/tinky-mouse/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ByteLandTechnology/tinky-mouse.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "ByteLand Technology Limited"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc && npm run docs",
+    "lint": "eslint src tests",
+    "prepublish": "npm run build",
+    "prepare": "husky",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --disableSources --out docs/api && prettier --write docs/api"
+  },
+  "files": [
+    "./bin/*",
+    "./lib/*"
+  ],
+  "typings": "./lib/index.d.ts",
+  "peerDependencies": {
+    "tinky": "^1.2.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/bun": "^1.3.6",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "semantic-release": "^25.0.2",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript-eslint": "^8.53.0"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write"
+  }
+}