@thazhemadam/vim-state 0.1.0

package/dist/editor/operators.js

@@ -0,0 +1,85 @@
+import { endOfBigWordPosition, endOfWordPosition, nextBigWordPosition, nextWordPosition, previousBigWordPosition, previousWordPosition, } from "./utils.js";
+/** Build the register metadata for a range without mutating editor state. */
+export function registerForRange(lines, range) {
+    return {
+        text: textForRange(lines, range),
+        type: range.type === "linewise" ? "linewise" : "charwise",
+    };
+}
+/** Resolve repeated word-ish motions without mutating the host editor. */
+export function countedWordPosition(lines, start, noun, count) {
+    let position = start;
+    for (let i = 0; i < count; ++i) {
+        const next = wordPosition(lines, position, noun);
+        if (samePosition(next, position)) {
+            return next;
+        }
+        position = next;
+    }
+    return position;
+}
+export function samePosition(left, right) {
+    return left.line === right.line && left.col === right.col;
+}
+/** Return a forward charwise range even when the motion destination is before the cursor. */
+export function normalizedCharRange(start, end) {
+    if (start.line < end.line ||
+        (start.line === end.line && start.col <= end.col)) {
+        return { type: "charwise", start, end };
+    }
+    return { type: "charwise", start: end, end: start };
+}
+/**
+ * Return how many forward deletes move text from `start` up to `end`.
+ *
+ * Crossing a line counts the newline separator as one deleted character, matching
+ * the host editor's repeated forward-delete behavior.
+ */
+export function deleteDistance(lines, start, end) {
+    if (start.line === end.line) {
+        return Math.max(end.col - start.col, 0);
+    }
+    let distance = (lines[start.line]?.length ?? 0) - start.col + 1;
+    for (let line = start.line + 1; line < end.line; ++line) {
+        distance += (lines[line]?.length ?? 0) + 1;
+    }
+    return distance + end.col;
+}
+/** Resolve one supported word-ish motion. */
+function wordPosition(lines, position, noun) {
+    switch (noun) {
+        case "nextWord":
+            return nextWordPosition(lines, position);
+        case "previousWord":
+            return previousWordPosition(lines, position);
+        case "endOfWord":
+            return endOfWordPosition(lines, position);
+        case "nextBigWord":
+            return nextBigWordPosition(lines, position);
+        case "previousBigWord":
+            return previousBigWordPosition(lines, position);
+        case "endOfBigWord":
+            return endOfBigWordPosition(lines, position);
+    }
+}
+/** Return the exact buffer text covered by a resolved operator range. */
+function textForRange(lines, range) {
+    switch (range.type) {
+        case "charwise":
+            return charwiseText(lines, range.start, range.end);
+        case "linewise":
+            return `${lines.slice(range.startLine, range.endLine + 1).join("\n")}\n`;
+    }
+}
+/** Return charwise text between two positions, preserving embedded newlines. */
+function charwiseText(lines, start, end) {
+    if (start.line === end.line) {
+        return (lines[start.line] ?? "").slice(start.col, end.col);
+    }
+    const chunks = [(lines[start.line] ?? "").slice(start.col)];
+    for (let line = start.line + 1; line < end.line; ++line) {
+        chunks.push(lines[line] ?? "");
+    }
+    chunks.push((lines[end.line] ?? "").slice(0, end.col));
+    return chunks.join("\n");
+}

package/dist/editor/types.d.ts

@@ -0,0 +1,118 @@
+/** Target accepted by line-jump commands. Numbers are 1-based like Vim counts. */
+export type VimLineTarget = number | "first" | "last";
+/** Single-character search operation that waits for a target character. */
+export type VimFindOperation = "find" | "till";
+/** Direction for single-character search operations. */
+export type VimFindDirection = "forward" | "backward";
+/** Target-character motion resolved after f/F/t/T receives its character. */
+export type VimFindTarget = {
+    type: "find";
+    operation: VimFindOperation;
+    direction: VimFindDirection;
+    char: string;
+};
+/** Operator-only text object target. */
+export type VimTextObject = {
+    type: "textObject";
+    kind: "inner" | "around";
+    object: "word";
+};
+/** Supported cursor motions understood by the current Vim editor core. */
+export type VimMotion = "left" | "down" | "up" | "right" | "lineStart" | "lineEnd" | "firstNonBlank" | "nextWord" | "previousWord" | "endOfWord" | "nextBigWord" | "previousBigWord" | "endOfBigWord";
+/** Pending operator plus the count captured before the operator key. */
+export type VimOperator = {
+    name: "delete" | "change" | "yank";
+    count?: number;
+};
+/** Unnamed-register payload captured by delete/change operations. */
+export type VimRegister = {
+    text: string;
+    type: "charwise" | "linewise";
+};
+export type VimEditorOptions = {
+    /**
+     * Called whenever an operation writes Vim's unnamed register.
+     * Hosts can use this to mirror the register to a system clipboard, remote
+     * clipboard, or any other external paste target. Leave unset to keep register
+     * writes inside Vim only.
+     */
+    onUnnamedRegisterWrite?: (register: VimRegister) => void;
+};
+/** Zero-based editor position. `col` is a UTF-16/string column for now. */
+export type VimPosition = {
+    line: number;
+    col: number;
+};
+export type VimVisualMode = "charwise" | "linewise";
+/** Visual selection anchor; the active end is the editor cursor. */
+export type VimVisualSelection = {
+    mode: VimVisualMode;
+    anchor: VimPosition;
+};
+/** Motion or operator-range noun an operator can act on (`line` backs doubled operators like `dd`). */
+export type VimNoun = VimMotion | VimFindTarget | VimTextObject | "line";
+export type VimOperatorTarget = VimNoun | VimVisualSelection;
+export type VimCaseTransform = "toggle" | "lower" | "upper";
+/**
+ * Minimal internal operator range model.
+ *
+ * Charwise ranges are cursor-position spans. Linewise ranges are whole row spans
+ * because Vim linewise operations ignore cursor column and carry different
+ * register/cursor semantics.
+ */
+export type VimRange = {
+    type: "charwise";
+    start: VimPosition;
+    end: VimPosition;
+} | {
+    type: "linewise";
+    startLine: number;
+    endLine: number;
+};
+/** Resolved real motion data: where motion lands and what range that motion covers for operators. */
+export type VimMotionResult = {
+    range: VimRange;
+    destination: VimPosition;
+};
+/** Semantic editor operations the Vim state machine can request. */
+export interface VimEditorApi extends Pick<VimEditorHost, "getCursor"> {
+    move(target: VimMotion | VimPosition): void;
+    insertLineBelow(): void;
+    insertLineAbove(): void;
+    joinLines(count?: number): void;
+    join(target: VimOperatorTarget): void;
+    goToLine(line: VimLineTarget): void;
+    moveToChar(operation: VimFindOperation, direction: VimFindDirection, char: string, count?: number): void;
+    placeCaretAtLineStart(): void;
+    placeCaretAfterCursor(): void;
+    placeCaretAtLineEnd(): void;
+    delete(target: VimOperatorTarget, count?: number): VimRegister | undefined;
+    change(target: VimOperatorTarget, count?: number): VimRegister | undefined;
+    yank(target: VimOperatorTarget, count?: number): VimRegister | undefined;
+    replace(target: VimOperatorTarget, replacement: VimRegister, emitRegisterWrite?: boolean): VimRegister | undefined;
+    transformCase(target: VimOperatorTarget, transform: VimCaseTransform): void;
+    put(register: VimRegister, placement: "before" | "after"): void;
+    replaceCharUnderCursor(char: string): void;
+    toggleCase(count?: number): void;
+    undo(): void;
+    redo(): void;
+    clampCursorColumn(): void;
+}
+/** Configuration operations exposed by a Vim editor. */
+export interface VimEditorConfiguration {
+    /** Replace the options used by subsequent editor operations. */
+    setOptions(options: VimEditorOptions): void;
+}
+/** Constructor accepted by the TypeScript mixin class-expression pattern. */
+export type Constructor<T = {}> = new (...args: any[]) => T;
+/** Primitive host-editor surface required by the reusable Vim composition mixin. */
+export interface VimEditorHost {
+    getCursor(): VimPosition;
+    getLines(): string[];
+    /** Restore the most recent host undo point, when supported. */
+    undoEditor?(): void;
+    /** Restore the most recent host redo point, when supported. */
+    redoEditor?(): void;
+    /** Forward raw input/control bytes to the underlying host editor. */
+    sendInputToEditor(data: string): void;
+}

package/dist/editor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils.d.ts

@@ -0,0 +1,85 @@
+import type { VimNoun, VimOperator } from "./types.js";
+/** Last valid Normal-mode cursor column for a line; empty lines stay at column 0. */
+export declare function normalMaxColumn(line: string): number;
+/** Column of the first non-blank character, or 0 for blank/empty lines. */
+export declare function firstNonBlankColumn(line: string): number;
+/**
+ * Return the next Normal-mode `w` target.
+ *
+ * Deliberately small Vim subset:
+ * - a run is a contiguous sequence of characters with the same `charType()`
+ * - word chars are ASCII letters, digits, and `_`
+ * - punctuation is any other non-whitespace run
+ * - whitespace is skipped after leaving the current run
+ * - scanning continues onto following lines
+ * - if no next run exists, clamp to the final Normal-mode cursor position
+ */
+export declare function nextWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/**
+ * Return the previous Normal-mode `b` target.
+ *
+ * Uses the same small run model as `nextWordPosition()`. The only special case
+ * is starting at the first character of a run: `b` skips that run and lands on
+ * the previous one instead of staying in place.
+ */
+export declare function previousWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/**
+ * Return the next Normal-mode `e` target.
+ *
+ * Uses the same small run model as `nextWordPosition()`. From whitespace it
+ * skips forward to the next run; from a run it lands on that run's end unless
+ * already there, in which case it advances to the next run's end.
+ */
+export declare function endOfWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/** Return the next whitespace-delimited WORD start for Normal-mode `W`. */
+export declare function nextBigWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/** Return the previous whitespace-delimited WORD start for Normal-mode `B`. */
+export declare function previousBigWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/** Return the next whitespace-delimited WORD end for Normal-mode `E`. */
+export declare function endOfBigWordPosition(lines: string[], cursor: {
+    line: number;
+    col: number;
+}): {
+    line: number;
+    col: number;
+};
+/**
+ * Resolve a Vim key into the noun/motion it names.
+ *
+ * With a pending operator, repeating the operator key means the current line
+ * (`dd`, later `cc`, `yy`). Otherwise keys are resolved through the shared
+ * normal-motion noun table.
+ */
+export declare function nounForKey(key: string, operator?: VimOperator): VimNoun | undefined;
+/** Return the same character with letter case flipped; non-letters are unchanged. */
+export declare function toggleCase(char: string): string;

package/dist/editor/utils.js

@@ -0,0 +1,206 @@
+import { NOUN_BY_KEY, OPERATOR_KEY } from "./constants.js";
+/** Last valid Normal-mode cursor column for a line; empty lines stay at column 0. */
+export function normalMaxColumn(line) {
+    return Math.max(line.length - 1, 0);
+}
+/** Column of the first non-blank character, or 0 for blank/empty lines. */
+export function firstNonBlankColumn(line) {
+    const match = /\S/.exec(line);
+    return match?.index ?? 0;
+}
+/**
+ * Return the next Normal-mode `w` target.
+ *
+ * Deliberately small Vim subset:
+ * - a run is a contiguous sequence of characters with the same `charType()`
+ * - word chars are ASCII letters, digits, and `_`
+ * - punctuation is any other non-whitespace run
+ * - whitespace is skipped after leaving the current run
+ * - scanning continues onto following lines
+ * - if no next run exists, clamp to the final Normal-mode cursor position
+ */
+export function nextWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : 0;
+        if (lineIndex === cursor.line &&
+            col < line.length &&
+            !isWhitespace(line[col])) {
+            const type = charType(line[col]);
+            while (col < line.length && charType(line[col]) === type) {
+                col += 1;
+            }
+        }
+        while (col < line.length && isWhitespace(line[col])) {
+            col += 1;
+        }
+        if (col < line.length) {
+            return { line: lineIndex, col };
+        }
+    }
+    const lastLine = Math.max(lines.length - 1, 0);
+    return { line: lastLine, col: normalMaxColumn(lines[lastLine] ?? "") };
+}
+/**
+ * Return the previous Normal-mode `b` target.
+ *
+ * Uses the same small run model as `nextWordPosition()`. The only special case
+ * is starting at the first character of a run: `b` skips that run and lands on
+ * the previous one instead of staying in place.
+ */
+export function previousWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex >= 0; lineIndex -= 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : line.length - 1;
+        while (col >= 0) {
+            while (col >= 0 && isWhitespace(line[col])) {
+                col -= 1;
+            }
+            if (col < 0) {
+                break;
+            }
+            const type = charType(line[col]);
+            let start = col;
+            while (start > 0 && charType(line[start - 1]) === type) {
+                start -= 1;
+            }
+            if (lineIndex !== cursor.line || start !== cursor.col) {
+                return { line: lineIndex, col: start };
+            }
+            col = start - 1;
+        }
+    }
+    return { line: 0, col: 0 };
+}
+/**
+ * Return the next Normal-mode `e` target.
+ *
+ * Uses the same small run model as `nextWordPosition()`. From whitespace it
+ * skips forward to the next run; from a run it lands on that run's end unless
+ * already there, in which case it advances to the next run's end.
+ */
+export function endOfWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : 0;
+        while (col < line.length) {
+            while (col < line.length && isWhitespace(line[col])) {
+                col += 1;
+            }
+            if (col >= line.length) {
+                break;
+            }
+            const type = charType(line[col]);
+            let end = col;
+            while (end + 1 < line.length && charType(line[end + 1]) === type) {
+                end += 1;
+            }
+            if (lineIndex !== cursor.line || end !== cursor.col) {
+                return { line: lineIndex, col: end };
+            }
+            col = end + 1;
+        }
+    }
+    const lastLine = Math.max(lines.length - 1, 0);
+    return { line: lastLine, col: normalMaxColumn(lines[lastLine] ?? "") };
+}
+/** Return the next whitespace-delimited WORD start for Normal-mode `W`. */
+export function nextBigWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : 0;
+        if (lineIndex === cursor.line &&
+            col < line.length &&
+            !isWhitespace(line[col])) {
+            while (col < line.length && !isWhitespace(line[col])) {
+                col += 1;
+            }
+        }
+        while (col < line.length && isWhitespace(line[col])) {
+            col += 1;
+        }
+        if (col < line.length) {
+            return { line: lineIndex, col };
+        }
+    }
+    const lastLine = Math.max(lines.length - 1, 0);
+    return { line: lastLine, col: normalMaxColumn(lines[lastLine] ?? "") };
+}
+/** Return the previous whitespace-delimited WORD start for Normal-mode `B`. */
+export function previousBigWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex >= 0; lineIndex -= 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : line.length - 1;
+        while (col >= 0) {
+            while (col >= 0 && isWhitespace(line[col])) {
+                col -= 1;
+            }
+            if (col < 0) {
+                break;
+            }
+            let start = col;
+            while (start > 0 && !isWhitespace(line[start - 1])) {
+                start -= 1;
+            }
+            if (lineIndex !== cursor.line || start !== cursor.col) {
+                return { line: lineIndex, col: start };
+            }
+            col = start - 1;
+        }
+    }
+    return { line: 0, col: 0 };
+}
+/** Return the next whitespace-delimited WORD end for Normal-mode `E`. */
+export function endOfBigWordPosition(lines, cursor) {
+    for (let lineIndex = cursor.line; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        let col = lineIndex === cursor.line ? cursor.col : 0;
+        while (col < line.length) {
+            while (col < line.length && isWhitespace(line[col])) {
+                col += 1;
+            }
+            if (col >= line.length) {
+                break;
+            }
+            let end = col;
+            while (end + 1 < line.length && !isWhitespace(line[end + 1])) {
+                end += 1;
+            }
+            if (lineIndex !== cursor.line || end !== cursor.col) {
+                return { line: lineIndex, col: end };
+            }
+            col = end + 1;
+        }
+    }
+    const lastLine = Math.max(lines.length - 1, 0);
+    return { line: lastLine, col: normalMaxColumn(lines[lastLine] ?? "") };
+}
+/**
+ * Resolve a Vim key into the noun/motion it names.
+ *
+ * With a pending operator, repeating the operator key means the current line
+ * (`dd`, later `cc`, `yy`). Otherwise keys are resolved through the shared
+ * normal-motion noun table.
+ */
+export function nounForKey(key, operator) {
+    if (operator && key === OPERATOR_KEY[operator.name]) {
+        return "line";
+    }
+    return NOUN_BY_KEY[key];
+}
+/** Return the same character with letter case flipped; non-letters are unchanged. */
+export function toggleCase(char) {
+    const lower = char.toLocaleLowerCase();
+    const upper = char.toLocaleUpperCase();
+    return char === lower && lower !== upper ? upper : lower;
+}
+/** Classify characters for the initial word-motion subset. */
+function charType(char) {
+    if (isWhitespace(char)) {
+        return "space";
+    }
+    return /[A-Za-z0-9_]/.test(char) ? "word" : "punct";
+}
+function isWhitespace(char) {
+    return /\s/.test(char);
+}

package/dist/editor.d.ts

@@ -0,0 +1 @@
+export * from "./editor/index.js";

package/dist/editor.js

@@ -0,0 +1 @@
+export * from "./editor/index.js";

package/dist/events.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Core Vim event vocabulary.
+ *
+ * Everything starts as a key. Printable characters are still keys: the current
+ * Vim mode decides whether `a` inserts text or runs the Normal-mode append
+ * command. Host-specific paste/IME handling belongs in adapters until we have
+ * a Vim-semantics reason to model it here.
+ */
+export interface VimKeyEvent {
+    type: "KEY";
+    key: string;
+}
+export type VimEvent = VimKeyEvent;

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/history.d.ts

@@ -0,0 +1,17 @@
+/** Linear undo/redo history with bounded snapshot stacks. */
+export declare class LinearHistory<Snapshot> {
+    private readonly maxSnapshots;
+    private readonly undoStack;
+    private readonly redoStack;
+    constructor(maxSnapshots?: number);
+    /** Remove all undo and redo snapshots. */
+    reset(): void;
+    /** Record a new edit boundary and discard any abandoned redo path. */
+    commit(snapshot: Snapshot): void;
+    /** Return the previous snapshot and move the current state onto redo. */
+    undo(current: Snapshot): Snapshot | undefined;
+    /** Return the next snapshot and move the current state back onto undo. */
+    redo(current: Snapshot): Snapshot | undefined;
+    /** Push a snapshot and discard the oldest entry if the stack is full. */
+    private pushBounded;
+}

package/dist/history.js

@@ -0,0 +1,44 @@
+/** Linear undo/redo history with bounded snapshot stacks. */
+export class LinearHistory {
+    maxSnapshots;
+    undoStack = [];
+    redoStack = [];
+    constructor(maxSnapshots = 100) {
+        this.maxSnapshots = maxSnapshots;
+    }
+    /** Remove all undo and redo snapshots. */
+    reset() {
+        this.undoStack.length = 0;
+        this.redoStack.length = 0;
+    }
+    /** Record a new edit boundary and discard any abandoned redo path. */
+    commit(snapshot) {
+        this.pushBounded(this.undoStack, snapshot);
+        this.redoStack.length = 0;
+    }
+    /** Return the previous snapshot and move the current state onto redo. */
+    undo(current) {
+        const snapshot = this.undoStack.pop();
+        if (!snapshot) {
+            return undefined;
+        }
+        this.pushBounded(this.redoStack, current);
+        return snapshot;
+    }
+    /** Return the next snapshot and move the current state back onto undo. */
+    redo(current) {
+        const snapshot = this.redoStack.pop();
+        if (!snapshot) {
+            return undefined;
+        }
+        this.pushBounded(this.undoStack, current);
+        return snapshot;
+    }
+    /** Push a snapshot and discard the oldest entry if the stack is full. */
+    pushBounded(stack, snapshot) {
+        stack.push(structuredClone(snapshot));
+        if (stack.length > this.maxSnapshots) {
+            stack.shift();
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./context.js";
+export * from "./editor.js";
+export * from "./events.js";
+export * from "./history.js";
+export * from "./machine.js";
+export * from "./selectors.js";
+export * from "./state.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./context.js";
+export * from "./editor.js";
+export * from "./events.js";
+export * from "./history.js";
+export * from "./machine.js";
+export * from "./selectors.js";
+export * from "./state.js";