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>.