@@ -8,68 +8,78 @@
88| helix-term | Terminal UI |
99| helix-tui | TUI primitives, forked from tui-rs, inspired by Cursive |
1010
11−# Notes
12−
13−- server-client architecture via gRPC, UI separate from core
14−- multi cursor based editing and slicing
15−- WASM based plugins (builtin LSP & fuzzy file finder)
16−
17−Structure similar to codemirror:
18−
19−- text (ropes)
20−- transactions
21− - changes
22− - invert changes (generates a revert)
23− - annotations (time changed etc)
24− - state effects
25− - additional editor state as facets
26−- snapshots as an async view into current state
27−- selections { anchor (nonmoving), head (moving) from/to } -> SelectionSet with a primary
28− - cursor is just a single range selection
29−- markers
30− track a position inside text that synchronizes with edits
31−- { doc, selection, update(), splice, changes(), facets, tabSize, identUnit, lineSeparator, changeFilter/transactionFilter to modify stuff before }
32−- view (actual UI)
33−- viewport(Lines) -> what's actually visible
34−- extend the view via Decorations (inline styling) or Components (UI)
35− - mark / wieget / line / replace decoration
36−- commands (transform state)
37−- movement
38−- selection extension
39−- deletion
40−- indentation
41−- keymap (maps keys to commands)
42−- history (undo tree via immutable ropes)
43− - undoes transactions via reverts
44−- (collab mode)
45−- gutter (line numbers, diagnostic marker, etc) -> ties into UI components
46−- rangeset/span -> mappable over changes (can be a marker primitive?)
47−- syntax (treesitter)
48−- fold
49−- selections (select mode/multiselect)
50−- matchbrackets
51−- closebrackets
52−- special-chars (shows dots etc for specials)
53−- panel (for UI: file pickers, search dialogs, etc)
54−- tooltip (for UI)
55−- search (regex)
56−- lint (async linters)
57−- lsp
58−- highlight
59−- stream-syntax
60−- autocomplete
61−- comment (gc, etc for auto commenting)
62−- snippets
63−- terminal mode?
64−
65−- plugins can contain more commands/ui abstractions to use elsewhere
66−- languageData as presets for each language (syntax, indent, comment, etc)
67−
68−Vim stuff:
69−- motions/operators/text objects
70−- full visual mode
71−- macros
72−- jump lists
73−- marks
74−- yank/paste
75−- conceal for markdown markers, etc
11+
12+This document contains a high-level overview of Helix internals.
13+
14+> NOTE: Use `cargo doc --open` for API documentation as well as dependency
15+> documentation.
16+
17+## Core
18+
19+The core contains basic building blocks used to construct the editor. It is
20+heavily based on [CodeMirror 6](https://codemirror.net/6/docs/). The primitives
21+are functional: most operations won't modify data in place but instead return
22+a new copy.
23+
24+The main data structure used for representing buffers is a `Rope`. We re-export
25+the excellent [ropey](https://github.com/cessen/ropey) library. Ropes are cheap
26+to clone, and allow us to easily make snapshots of a text state.
27+
28+Multiple selections are a core editing primitive. Document selections are
29+represented by a `Selection`. Each `Range` in the selection consists of a moving
30+`head` and an immovable `anchor`. A single cursor in the editor is simply
31+a selection with a single range, with the head and the anchor in the same
32+position.
33+
34+Ropes are modified by constructing an OT-like `Transaction`. It's represents
35+a single coherent change to the document and can be applied to the rope.
36+A transaction can be inverted to produce an undo. Selections and marks can be
37+mapped over a transaction to translate to a position in the new text state after
38+applying the transaction.
39+
40+> NOTE: `Transaction::change`/`Transaction::change_by_selection` is the main
41+> interface used to generate text edits.
42+
43+`Syntax` is the interface used to interact with tree-sitter ASTs for syntax
44+highling and other features.
45+
46+## View
47+
48+The `view` layer was supposed to be a frontend-agnostic imperative library that
49+would build on top of `core` to provide the common editor logic. Currently it's
50+tied to the terminal UI.
51+
52+A `Document` ties together the `Rope`, `Selection`(s), `Syntax`, document
53+`History`, language server (etc.) into a comprehensive representation of an open
54+file.
55+
56+A `View` represents an open split in the UI. It holds the currently open
57+document ID and other related state.
58+
59+> NOTE: Multiple views are able to display the same document, so the document
60+> contains selections for each view. To retrieve, `document.selection()` takes
61+> a `ViewId`.
62+
63+The `Editor` holds the global state: all the open documents, a tree
64+representation of all the view splits, and a registry of language servers. To
65+open or close files, interact with the editor.
66+
67+## LSP
68+
69+A language server protocol client.
70+
71+## Term
72+
73+The terminal frontend.
74+
75+The `main` function sets up a new `Application` that runs the event loop.
76+
77+`commands.rs` is probably the most interesting file. It contains all commands
78+(actions tied to keybindings).
79+
80+`keymap.rs` links commands to key combinations.
81+
82+
83+## TUI / Term
84+
85+TODO: document Component and rendering related stuff