# @gregorlohaus/codemirror-helix

[Helix](https://helix-editor.com/)-style modal editing for [CodeMirror 6](https://codemirror.net/).

Selection-first editing with multiple selections, Normal/Insert/Select modes,
goto & match modes, textobjects, surround, registers, counts, and search.

> A **core motions subset** — broad coverage of everyday Helix keys, not full
> parity. No tree-sitter textobjects, LSP gotos, macros, or jumplist.

## Install

```sh
bun add @gregorlohaus/codemirror-helix
# peers: @codemirror/{state,view,commands,language,search}
```

## Usage

```ts
import { EditorView, basicSetup } from "codemirror";
import { helix } from "@gregorlohaus/codemirror-helix";

new EditorView({
  doc: "hello world",
  extensions: [basicSetup, helix()],
  parent: document.body,
});
```

`helix()` needs a selection drawer for multi-cursor rendering — `basicSetup`
(or `drawSelection()`) covers it.

### Options

```ts
helix({
  startInInsert: false, // start in Normal mode (default)
  statusBar: true,      // show the bottom mode line
  // Let an open autocomplete popup eat the first Escape instead of leaving Insert:
  escapeGuard: (state) => completionStatus(state) === "active",
});
```

## Keys

Starts in **Normal** mode. The status line shows the mode, pending count,
register, and selection count.

| Group | Keys |
| --- | --- |
| Modes | `i`/`a` insert before/after, `I`/`A` line start/end, `o`/`O` open line, `v` select (extend), `Esc` normal |
| Motion | `h j k l`, `w W b B e E`, `f t F T {char}`, `Alt-.` repeat find, `Home`/`End`, counts (`3w`) |
| Goto `g` | `gg`/`Ng` line, `ge` end, `gh`/`gl` line ends, `gs` first non-blank, `gt`/`gc`/`gb` view top/center/bottom |
| Select | `x` line (repeat extends), `X` line bounds, `%` all, `;` collapse, `Alt-;` flip, `Alt-:` forward, `,` keep primary, `Alt-,` remove primary, `(`/`)` rotate, `_` trim |
| Multi | `s` select regex, `S` split, `K`/`Alt-K` keep/remove, `C` copy selection below, `Alt-C` above |
| Match `m` | `mm` matching bracket, `mi{o}`/`ma{o}` inside/around (`w W p ( [ { < " ' \` m`), `ms{c}` surround, `md{c}` delete, `mr{c}{c}` replace |
| Edit | `d` delete, `c` change, `y` yank, `p`/`P` paste, `R` replace w/ register, `r{c}` replace char, `~`/`` ` ``/`Alt-`` ` `` case, `J` join, `>`/`<` indent, `u`/`U` undo/redo |
| Registers | `"{c}` select register for the next yank/delete/paste |
| Search | `/` `?` search, `n`/`N` next/prev, `*` search selection |
| View | `zz`/`zt`/`zb` center/top/bottom, `Ctrl-d`/`Ctrl-u` half page, `Ctrl-f`/`Ctrl-b` page |
| Clipboard | `space y` copy, `space p`/`space P` paste (system clipboard) |

`s`/`S`/`K`/`Alt-K` open a prompt and preview live as you type the regex;
`Enter` commits, `Esc` restores the original selection.

## License

MIT