rwb-codemirror-helix 0.2.0

package/README.md

@@ -0,0 +1,331 @@
+# codemirror-helix
+
+A vibe-coded, in the sense that I literally have not looked at the code, set of Helix keybindings for CodeMirror 6.
+That said, it's fairly complete and works for my purposes (read: getting Helix keybindings in Obsidian).
+
+--- Everything past this is LLM generated; read at your own risk. ---
+
+## Features
+
+- **Normal / Insert / Select modes** with block cursor and per-mode CSS classes
+- **Motions**: `h j k l w b e W B E f F t T ; , Alt-. 0 Home End G %`
+- **Count prefixes**: `5j`, `3w`, `10l`, …
+- **g-prefix** (goto): `gg` `ge` `gh` `gl` `gs` `gt` `gc` `gb` `gj` `gk` `g.` `gw` `g|`
+- **z-prefix** (view): `zz` `zt` `zb` `zj` `zk`; `Z` sticky view mode
+- **m-prefix** (match/surround/text-objects): `mm` `ms` `mr` `md` `mi` `ma`
+- **`[ ]` prefixes**: `]p` `[p` `]Space` `[Space`
+- **Editing**: `d` `Alt-d` `c` `Alt-c` `y` `p` `P` `R` `r` `~` `` ` `` `Alt-`` ` `` `>` `<` `J` `Alt-J` `.` `u` `U` `Ctrl-a` `Ctrl-x` `&` `_`
+- **Multi-cursor**: `C` `Alt-C` `s` `S` `Alt-s` `K` `Alt-K` `)` `(` `Alt-)` `Alt-(` `Alt--` `Alt-_` `Alt-,` `,`
+- **Named registers**: `"ay` `"ap` — yank/paste with any letter register
+- **Surround**: `ms(` `md(` `mr('`
+- **Text objects**: `miw` `maw` `mi(` `ma{` `mi"` …
+- **Search**: `/` `?` `n` `N` `*` `Alt-*` — regex-capable inline panel
+- **Jump list**: `Ctrl-s` `Ctrl-o` `Ctrl-i`
+- **Insert mode helpers**: `Ctrl-w` `Alt-Backspace` `Alt-d` `Alt-Delete` `Ctrl-h` `Ctrl-d` `Delete` `Ctrl-u` `Ctrl-k` `Ctrl-s` `Enter` `Ctrl-r`
+- **Status bar** showing current mode, count, pending operation, active register, and cursor position
+- **Dot-repeat** (`.`) and **undo/redo** (`u` / `U`)
+
+## Installation
+
+```bash
+npm install rwb-codemirror-helix
+```
+
+`@codemirror/state` and `@codemirror/view` are peer dependencies and must be installed separately.
+
+## Usage
+
+```ts
+import { EditorView } from "@codemirror/view";
+import { EditorState } from "@codemirror/state";
+import { helixKeymap } from "codemirror-helix";
+
+const view = new EditorView({
+  state: EditorState.create({
+    doc: "Hello, world!",
+    extensions: [
+      helixKeymap(),
+      // ... your other extensions
+    ],
+  }),
+  parent: document.getElementById("editor"),
+});
+```
+
+### Options
+
+```ts
+helixKeymap({
+  // Show the status bar panel at the bottom of the editor. Default: true
+  statusBar: true,
+})
+```
+
+### Reading the current mode
+
+```ts
+import { getHelixMode } from "codemirror-helix";
+
+const mode = getHelixMode(view.state); // "normal" | "insert" | "select"
+```
+
+You can also subscribe to mode changes via the exported `helixStateField`:
+
+```ts
+import { helixStateField } from "codemirror-helix";
+
+// Inside a ViewPlugin or updateListener:
+const { mode } = update.state.field(helixStateField);
+```
+
+### CSS customisation
+
+The editor root element receives a class for the current mode:
+
+| Mode   | Class                 |
+|--------|-----------------------|
+| Normal | `helix-mode-normal`   |
+| Insert | `helix-mode-insert`   |
+| Select | `helix-mode-select`   |
+
+Status bar colours and the block cursor can be overridden with CSS variables.
+By default the status bar inherits the editor's background and foreground, so
+it blends in with any theme. The mode indicator colours are chosen to be legible
+on light backgrounds; override them for a dark theme:
+
+```css
+/* Example: dark theme overrides */
+.cm-editor {
+  --helix-status-bg:      #2d2d2d;
+  --helix-status-fg:      #ccc;
+  --helix-status-border:  #444;
+  --helix-normal-color:   #5af;
+  --helix-insert-color:   #8f8;
+  --helix-select-color:   #fa8;
+  --helix-count-color:    #ff8;
+  --helix-pending-color:  #aaa;
+  --helix-register-color: #c8f;
+}
+```
+
+## Keybinding reference
+
+### Normal mode
+
+#### Movement
+
+| Key | Action |
+|-----|--------|
+| `h` / `←` | Move left |
+| `l` / `→` | Move right |
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `w` | Next word start |
+| `b` | Previous word start |
+| `e` | Next word end |
+| `W` `B` `E` | Same, WORD (whitespace-delimited) |
+| `f<c>` | Find char forward on line |
+| `F<c>` | Find char backward on line |
+| `t<c>` | Till char forward (one before) |
+| `T<c>` | Till char backward (one after) |
+| `Alt-.` | Repeat last `f`/`F`/`t`/`T` |
+| `0` / `Home` | Line start |
+| `End` | Line end |
+| `%` | Select entire file |
+| `Ctrl-d` | Scroll half page down |
+| `Ctrl-u` | Scroll half page up |
+| `Ctrl-f` / `PageDown` | Scroll page down |
+| `Ctrl-b` / `PageUp` | Scroll page up |
+
+#### g-prefix (goto)
+
+| Key | Action |
+|-----|--------|
+| `gg` | Go to file start (or line N with count) |
+| `ge` | Go to file end |
+| `gh` | Go to line start |
+| `gl` | Go to line end |
+| `gs` | Go to first non-whitespace |
+| `gt` | Go to top of screen |
+| `gc` | Go to middle of screen |
+| `gb` | Go to bottom of screen |
+| `gj` | Move down (same as `j`) |
+| `gk` | Move up (same as `k`) |
+| `g.` | Go to last modification |
+| `gw` | Jump-to-word (two-key label overlay) |
+| `g|` | Go to column N (1-based, with count) or line start |
+| `G` | Go to last line (or line N with count) |
+
+#### z-prefix (view)
+
+| Key | Action |
+|-----|--------|
+| `zz` / `zc` | Center cursor on screen |
+| `zt` | Scroll cursor to top |
+| `zb` | Scroll cursor to bottom |
+| `zj` / `zk` | Scroll one line down / up |
+| `Z` | Enter sticky view mode (view keys stay active until `Escape`) |
+
+#### Selection
+
+| Key | Action |
+|-----|--------|
+| `v` | Enter Select mode |
+| `V` | Select current line and enter Select mode |
+| `x` | Select current line |
+| `X` | Extend to full line bounds |
+| `Alt-x` | Shrink to line content |
+| `;` | Collapse selection to cursor |
+| `Alt-;` | Flip selection anchor/head |
+| `Alt-:` | Ensure selection is forward |
+| `,` | Keep only primary selection |
+| `Alt-,` | Remove primary selection |
+| `)` | Rotate primary selection forward |
+| `(` | Rotate primary selection backward |
+
+#### Multi-cursor
+
+| Key | Action |
+|-----|--------|
+| `C` | Copy selection to next line |
+| `Alt-C` | Copy selection to previous line |
+| `s` | Select within selection (regex prompt) |
+| `S` | Split selection on delimiter (regex prompt) |
+| `Alt-s` | Split selections on newlines |
+| `K` | Keep selections matching regex |
+| `Alt-K` | Remove selections matching regex |
+| `Alt-_` | Merge consecutive/overlapping selections |
+| `Alt--` | Merge all selections into one |
+| `Alt-)` | Rotate selection contents forward |
+| `Alt-(` | Rotate selection contents backward |
+
+#### Editing
+
+| Key | Action |
+|-----|--------|
+| `d` | Delete selection (yanked) |
+| `Alt-d` | Delete without yanking |
+| `c` | Change selection (delete + insert) |
+| `Alt-c` | Change without yanking |
+| `y` | Yank selection |
+| `p` | Paste after |
+| `P` | Paste before |
+| `R` | Replace selection with yanked text |
+| `r<c>` | Replace each char in selection with `<c>` |
+| `u` | Undo |
+| `U` | Redo |
+| `J` | Join lines |
+| `Alt-J` | Join lines and select the inserted space |
+| `~` | Toggle case |
+| `` ` `` | Lowercase selection |
+| `Alt-`` ` `` | Uppercase selection |
+| `>` | Indent |
+| `<` | Unindent |
+| `_` | Trim leading/trailing whitespace from selection |
+| `.` | Repeat last change |
+| `Ctrl-a` | Increment number under cursor |
+| `Ctrl-x` | Decrement number under cursor |
+| `Ctrl-c` | Toggle line comment |
+| `&` | Align selections (insert spaces to align `from` positions) |
+| `"<r>` | Select register `<r>` for next yank/paste |
+
+#### m-prefix (match / surround / text objects)
+
+| Key | Action |
+|-----|--------|
+| `mm` | Jump to matching bracket |
+| `ms<c>` | Surround selection with `<c>` |
+| `md<c>` | Delete surrounding `<c>` |
+| `mr<from><to>` | Replace surrounding `<from>` with `<to>` |
+| `miw` | Select inside word |
+| `maw` | Select around word (includes trailing space) |
+| `mi(` `mi[` `mi{` | Select inside bracket pair |
+| `ma(` `ma[` `ma{` | Select around bracket pair |
+| `mi"` `mi'` `` mi` `` | Select inside quotes |
+
+Surround characters: `(` `)` `[` `]` `{` `}` `<` `>` and any symmetric char (e.g. `"`).
+
+#### [ / ] prefixes
+
+| Key | Action |
+|-----|--------|
+| `]p` | Move to next paragraph |
+| `[p` | Move to previous paragraph |
+| `]Space` | Add blank line below |
+| `[Space` | Add blank line above |
+
+#### Search
+
+| Key | Action |
+|-----|--------|
+| `/` | Open search forward |
+| `?` | Open search backward |
+| `n` | Go to next match |
+| `N` | Go to previous match |
+| `*` | Search for word under cursor |
+| `Alt-*` | Search for selection (no word boundaries) |
+
+Search supports full JavaScript regex syntax.
+
+#### Jump list
+
+| Key | Action |
+|-----|--------|
+| `Ctrl-s` | Save current position to jump list |
+| `Ctrl-o` | Jump back |
+| `Ctrl-i` | Jump forward |
+
+### Insert mode
+
+| Key | Action |
+|-----|--------|
+| `Escape` | Return to Normal mode |
+| `Ctrl-w` / `Alt-Backspace` | Delete previous word |
+| `Alt-d` / `Alt-Delete` | Delete next word |
+| `Ctrl-h` | Delete previous character |
+| `Ctrl-d` / `Delete` | Delete next character |
+| `Ctrl-u` | Delete to line start |
+| `Ctrl-k` | Delete to line end |
+| `Enter` / `Ctrl-j` | New line with indentation |
+| `Ctrl-s` | Commit undo checkpoint |
+| `Ctrl-r<r>` | Paste from register `<r>` |
+
+### Entering Insert mode (from Normal)
+
+| Key | Action |
+|-----|--------|
+| `i` | Insert before selection |
+| `a` | Insert after selection |
+| `I` | Insert at line start |
+| `A` | Insert at line end |
+| `o` | Open new line below |
+| `O` | Open new line above |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run the demo app (hot-reloading)
+npm run dev
+
+# Run tests
+npm test
+
+# Type-check
+npm run typecheck
+
+# Build the library
+npm run build
+```
+
+## What's not implemented
+
+- **Macros** (`q` / `@`)
+- **Command-line mode** (`:` prompt)
+- **LSP commands** (`gd`, `gr`, Space-mode) — require a language server
+
+## License
+
+MIT