Code folding

[DubrovinEIu]

Related to #1840

Screencast.From.2025-10-13.16-37-20.mp4

New user-level items

Introduced text folding commands:

1. fold (default key-mapping is zf)
2. unfold (default key-mapping is zF)
3. :fold
4. :unfold

Added the field fold_textobjects to editor (default list is empty, try to add some of the following available textobjects: class, function, comment)
Added the style ui.virtual.fold-decoration

Commands that ignore folded text

The following commands behave as if there is no folded text.

Move word:

1. move_next_word_start
2. move_prev_word_start
3. move_prev_word_end
4. move_next_word_end
5. move_next_long_word_start
6. move_prev_long_word_start
7. move_prev_long_word_end
8. move_next_long_word_end
9. move_next_sub_word_start
10. move_prev_sub_word_start
11. move_prev_sub_word_end
12. move_next_sub_word_end

Extend word:

1. extend_next_word_start
2. extend_prev_word_start
3. extend_next_word_end
4. extend_prev_word_end
5. extend_next_long_word_start
6. extend_prev_long_word_start
7. extend_prev_long_word_end
8. extend_next_long_word_end
9. extend_next_sub_word_start
10. extend_prev_sub_word_start
11. extend_prev_sub_word_end
12. extend_next_sub_word_end

Move paragraph:

1. goto_prev_paragraph
2. goto_next_paragraph

Find char:

1. find_till_char
2. find_next_char
3. extend_till_char
4. extend_next_char
5. till_prev_char
6. find_prev_char
7. extend_till_prev_char
8. extend_prev_char

Extend line:

1. extend_line
2. extend_line_above
3. extend_line_below

Open:

1. open_below

To last line:

1. goto_last_line
2. extend_to_last_line

Paste:

1. paste_after

Goto TS object:
NOTE: the commands skip only entire folded TS objects

1. goto_next_function
2. goto_prev_function
3. goto_next_class
4. goto_prev_class
5. goto_next_parameter
6. goto_prev_parameter
7. goto_next_comment
8. goto_prev_comment
9. goto_next_test
10. goto_prev_test
11. goto_next_xml_element
12. goto_prev_xml_element
13. goto_next_entry
14. goto_prev_entry

To word:

1. goto_word
2. extend_to_word

Actions that create folds

Split:
NOTE: commands copy folds to the new view

1. hsplit
2. vsplit
3. :hsplit
4. :vsplit

File:
NOTE: when a new buffer is opened the specified text objects in the field fold_textobjects are folded.

1. file_picker
2. file_explorer
3. cli pathspec (e.g., the command hx -- src/main.rs will open the file and fold the text objects defined in fold_textobjects)

Accompanying changes

1. Replaced CharMatcher with GraphemeMatcher.
   For more details, check the commit f320270.
2. Fixed the method TextObjectQuery::capture_nodes_any (issue "Match around comment" not selecting full commented block made of line comments #11087)
   Also, the fix was pushed as PR Fixed matching around comment #14591.

Speech

Fold primitives have been implemented, including all components related to rendering and text processing.
However, user-items are currently in draft form. Perhaps someone could suggest more convenient commands. Therefore, the documentation has not yet been written.
I suggest applying this PR in order for master-users to test the new feature and open an issue related to text folding.

Check the commit history for details. I have been trying to make it readable, consistent, and organized.
Start by reading the top-level documentation of the text_folding module.

Planned improvements

Enable language-specific text folding.

[Bleksak]

would it make sense to add toggle-fold command too?

[DubrovinEIu]

Added the command toggle_fold.
Default key-mapping is z<A-f>.

[damianoognissanti]

One of my favourite features in my vim setup is code that connects a search folding plugin to the multiple cursors plugin.
Is that what the -s flag does?

EDIT: I built it now and the -s flag does not do this, so this is a feature request, if it's not too hard to implement :-)

What I have is basically a command that toggles folds based on the word I searched for (I assume in helix it would make more sense to fold based on selections? Or both?) which makes it possible to see lines that you work on, even if they are far apart. I also have a command that toggles how many lines are visible around the fold, so I can for example choose to see cursor +- 3 lines.

I have added a screenshot showing cursor +- 1 line as a reference.

[diniamo]

Would it not be better to bind only the toggle command to zf by default? I would always use toggle binds over on/off, since it feels like less mental overhead.