From c87d310f7af5a37b65d450c97e1574bde9fe11fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Fri, 17 Oct 2025 23:34:17 -0500 Subject: [PATCH] docs: Starting point for minimode and helix mode --- content/docs/architecture/minimode.smd | 110 +++++++++++++++++++++++++ content/docs/mode/helix.smd | 67 +++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 content/docs/architecture/minimode.smd create mode 100644 content/docs/mode/helix.smd diff --git a/content/docs/architecture/minimode.smd b/content/docs/architecture/minimode.smd new file mode 100644 index 0000000..834ec16 --- /dev/null +++ b/content/docs/architecture/minimode.smd @@ -0,0 +1,110 @@ +--- +.title = "Minimodes", +.date = @date("2025-10-15T00:00:00"), +.author = "Igor Támara", +.layout = "index.shtml", +.draft = false, +--- + +Minimodes can be used by other modes adding functionality +to the editor, they have their own set of keybindings and +are used momentarily for an specific action, i.e. find +something in the current buffer or in project files, +open/save a file, and, in modal modes(like vim and helix). +An example of the latter is using numeric prefixes to +repeat an action many times. + +## Anatomy of minimodes + +To create a minimode it's needed: + +* A Keybinding +* An Action mapping +* A Minimode definition + +### Keybinding + +When a key or a keystroke(set of keys) are pressed, the +associated minimode gets activated and will start to +capture the key/strokes until a special keybinding +makes it exit, or an specific action exits the minimode. +Head to `src/keybind/builtin/flow.json`(flow keybinds) +and look for `mini_find`, where you will know which +specific actions are triggered by the keybindings of the +minimode. + +### Action mapping + +Actions executed by each minimode are stored one per +file under `src/tui/mode/mini/`. The command that +opens opens the door to the minimode is linked from +`src/tui/tui.zig` which calls them dynamically when needed. + +Look for `mini` inside `tui.zig` to find out which minimodes +are present and where to look to learn how each minimode +does its own task. + +### Minimode definition + +Possibly the simplest minimode that will be found that does +not require defining a particular widget is the `replace` +minimode, used in helix mode and vim mode. To enter the +minimode in Helix while in `NOR` or `INS` use the keybind +**r**, it consumes another key and replaces the current +character under the main cursor with the pressed key. +If there are multiple selections, all the characters are +replaced by the one typed after **r**. + +- The minimode needs to expose a `create` function with +type + +```zig +pub fn create(Allocator,command.Context) !struct { tui.Mode, tui.MiniMode } +``` +Which is in charge of registering the minimode to be able +to receive events and will offer the minimode name, the +one that appears in the lower status bar while it is active, +to let it be known that the minimode is active. This is +where all the instatiations are made. Which leads to + +- The `deinit` function whose type is + +```zig +pub fn deinit(*Self) +``` + +- A `receive` function that will route events received +casting the type: + +```zig +pub fn receive(*Self, tp.pid_ref, tp.message) error{Exit}!bool +``` + +- A `commands` field that will expose the minimode `Collection` +of `Commands`. + +An special command `mini_mode_insert_code_point` as an element +of the commands collection with type: + +```zig +pub fn mini_mode_insert_code_point(*Self, Ctx) Result +``` + +acting as the default handler of the key presses that the minimode +will receive when there is no other defined. + +All the keys were handled and managed by the default "invisible" +widget that processes the keys for the minimode. And there is +room for custom widgets that are explained next. + +## A custom widget + +When there is a need for an specialized widget, it's possible to +define one, for example, the `file_browser` is used to load and +save files, and `numeric_input` is used to set the tab width for +example(look for it in the command palette `:`). + + +* Head to [architecture](/docs/architecture) +* Learn about [commands](/docs/architecture/command) +* Review [keybindings](/docs/architecture/keybind) diff --git a/content/docs/mode/helix.smd b/content/docs/mode/helix.smd new file mode 100644 index 0000000..62b5606 --- /dev/null +++ b/content/docs/mode/helix.smd @@ -0,0 +1,67 @@ +--- +.title = "Helix Mode", +.date = @date("2025-10-10T00:00:00"), +.author = "Igor Támara", +.layout = "index.shtml", +.draft = false, +--- + +This document describes implementation of Helix Mode. + +## What and what not + +The first and biggest difference is that Flow has a mode that +emulates Helix, or at least has equivalent of the worthiest +actions that can be done in Helix. The conversely is not true. + +`:` opens up Flow's rich command palette that might have +functionalities Helix users are used to have, if you find +something missing, it's possible to +[open a Feature Request](https://github.com/neurocyte/flow/issues) +to see if there is anyone interested in porting it. Or maybe +someone is already creating or interested in the one you are +missing. [Join Discord](https://discord.gg/kzJC9fA7) to ask +if anyone is working on something similar or there is a +workaoround. + +## Enhancing hx mode + +This is a programmer editor, you are more than welcome to +enhance to suit your needs that maybe coincide with others. + +Please take a look at [architecture](/docs/architecture) and +[contributing](/docs/contributing) for an overview and the +mechanics of getting your changes into Flow. + +hx mode is modal kind, the same as vim mode, and the file +that has the particular work to make it real is in +`src/tui/mode/helix.zig`, adding a `command` and the +corresponding `meta` is what is required. +[More on commands](/docs/architecture/command). + +### Pickers + +Flow hx mode offers most of the picker types equivalents +with `panels` and `palettes`. Example of panels are +the `g` `r` (go to reference from lsp) and `space` `/` +(a.k.a find in files). Examples of `palettes` are +`space` `b` to pick a buffer or `space` `f` to open a +file in your project. Panels open below the editor +while palettes open overlapping the working area. + +One medium sized project is to create a widget that +has one input widget, two panels, on the left the +list of options and on the right the preview of +the selected option and offer various keybindings +to manipulate the objects inside both panels with +filtering. + +Given this, it's possible to start contributing via +pull requesting [keybinds](/docs/architecture/keybind), +[commands](/docs/architecture/command), +[palettes](/docs/architecture/palette), or the +special widget mentioned previously. + + +More about the [architecture](/docs/architecture) or jump to +[contribution guidelines](/docs/contributing). \ No newline at end of file