Exit snippets upon jumping to $0 (close #1161)

This restores the pre-d9cb6ab-behaviour of completely leaving a snippet once $0 is reached, instead of leaving the possibility of jumping back into it.
This behaviour can be turned on or off via `exit_roots`, and, like the other settings that superseded `history`, `exit_roots` will be set s.t. `history` still/again behaves as expected.

DOC.md

@@ -3502,11 +3502,17 @@ These are the settings you can provide to `luasnip.setup()`:
   [Basics-Snippet-Insertion](#snippet-insertion) for more context.
 - `link_roots`: Whether snippet-roots should be linked. See
   [Basics-Snippet-Insertion](#snippet-insertion) for more context.
+- `exit_roots`: Whether snippet-roots should exit at reaching at their last
+  node, `$0`. This setting is only valid for root snippets, not child snippets.
+  This setting may avoid unexpected behavior by disallowing to jump earlier
+  (finished) snippets. Check [Basics-Snippet-Insertion](#snippet-insertion) for
+  more information on snippet-roots.
 - `link_children`: Whether children should be linked. See
   [Basics-Snippet-Insertion](#snippet-insertion) for more context.
 - `history` (deprecated): if not nil, `keep_roots`, `link_roots`, and
-  `link_children` will bet set to the value of `history`.  
-  This is just to ensure backwards-compatibility.
+  `link_children` will be set to the value of `history`, and
+  `exit_roots` will set to inverse value of `history`. This is just to ensure
+  backwards-compatibility.
 - `update_events`: Choose which events trigger an update of the active nodes'
   dependents. Default is just `'InsertLeave'`, `'TextChanged,TextChangedI'`
   would update on every change.

doc/luasnip.txt

@@ -1,4 +1,4 @@
-*luasnip.txt*            For NVIM v0.8.0            Last change: 2024 April 24
+*luasnip.txt*            For NVIM v0.8.0            Last change: 2024 April 26
 
 ==============================================================================
 Table of Contents                                  *luasnip-table-of-contents*
@@ -3372,10 +3372,16 @@ These are the settings you can provide to `luasnip.setup()`:
     |luasnip-basics-snippet-insertion| for more context.
 - `link_roots`: Whether snippet-roots should be linked. See
     |luasnip-basics-snippet-insertion| for more context.
+- `exit_roots`: Whether snippet-roots should exit at reaching at their last node,
+    `$0`. This setting is only valid for root snippets, not child snippets. This
+    setting may avoid unexpected behavior by disallowing to jump earlier (finished)
+    snippets. Check |luasnip-basics-snippet-insertion| for more information on
+    snippet-roots.
 - `link_children`: Whether children should be linked. See
     |luasnip-basics-snippet-insertion| for more context.
 - `history` (deprecated): if not nil, `keep_roots`, `link_roots`, and
-    `link_children` will bet set to the value of `history`. This is just to ensure
+    `link_children` will be set to the value of `history`, and `exit_roots` will
+    set to inverse value of `history`. This is just to ensure
     backwards-compatibility.
 - `update_events`: Choose which events trigger an update of the active nodes’
     dependents. Default is just `'InsertLeave'`, `'TextChanged,TextChangedI'` would

lua/luasnip/config.lua

@@ -58,6 +58,7 @@ c = {
 		if user_config.history ~= nil then
 			conf.keep_roots = user_config.history
 			conf.link_roots = user_config.history
+			conf.exit_roots = not user_config.history
 			conf.link_children = user_config.history
 
 			-- unset key to prevent handling twice.

lua/luasnip/default_config.lua

@@ -103,6 +103,7 @@ return {
 	-- corresponds to legacy "history=false".
 	keep_roots = false,
 	link_roots = false,
+	exit_roots = true,
 	link_children = false,
 
 	update_events = "InsertLeave",

lua/luasnip/init.lua

@@ -159,8 +159,18 @@ end
 local function jump(dir)
 	local current = session.current_nodes[vim.api.nvim_get_current_buf()]
 	if current then
-		session.current_nodes[vim.api.nvim_get_current_buf()] =
-			util.no_region_check_wrap(safe_jump_current, dir)
+		local next_node = util.no_region_check_wrap(safe_jump_current, dir)
+		if next_node == nil then
+			session.current_nodes[vim.api.nvim_get_current_buf()] = nil
+			return true
+		end
+		if session.config.exit_roots then
+			if next_node.pos == 0 and next_node.parent.parent_node == nil then
+				session.current_nodes[vim.api.nvim_get_current_buf()] = nil
+				return true
+			end
+		end
+		session.current_nodes[vim.api.nvim_get_current_buf()] = next_node
 		return true
 	else
 		return false

tests/integration/session_spec.lua

@@ -20,7 +20,10 @@ describe("session", function()
 
 	before_each(function()
 		ls_helpers.clear()
-		ls_helpers.session_setup_luasnip({ hl_choiceNode = true })
+		ls_helpers.session_setup_luasnip({
+			setup_extend = { exit_roots = false },
+			hl_choiceNode = true,
+		})
 
 		-- add a rather complicated snippet.
 		-- It may be a bit hard to grasp, but will cover lots and lots of
@@ -700,6 +703,7 @@ describe("session", function()
 			exec_lua(([[
 				ls.setup({
 					link_children = %s,
+					exit_roots = false,
 				})
 			]]):format(link_children_val))
 
@@ -1466,6 +1470,7 @@ describe("session", function()
 			ls.setup({
 				keep_roots = true,
 				link_roots = true,
+				exit_roots = false,
 				link_children = true,
 				delete_check_events = "TextChanged",
 				ext_opts = {
@@ -1928,6 +1933,7 @@ describe("session", function()
 			ls.setup({
 				keep_roots = true,
 				link_roots = true,
+				exit_roots = false,
 				link_children = true
 			})
 		]])

tests/integration/snippet_basics_spec.lua

@@ -1326,6 +1326,108 @@ describe("snippets_basic", function()
 		})
 	end)
 
+	it(
+		"exit_roots exits when the last node of snippet-root is reached.",
+		function()
+			exec_lua([[
+			ls.setup({
+				exit_roots = true
+			})
+			ls.add_snippets("all", {
+			s("aa", { t{"( "}, i(1, "1"), t{" )"}, i(0, "0") })
+			})
+		]])
+
+			feed("iaa")
+			exec_lua("ls.expand()")
+			screen:expect({
+				grid = [[
+			( ^1 )0                                            |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+			})
+			feed("aa")
+			exec_lua("ls.expand()")
+			screen:expect({
+				grid = [[
+			( ( ^1 )0 )0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+			})
+			-- verify we do not exit when reaching to a child root
+			exec_lua("ls.jump(1) ls.jump(-1)")
+			screen:expect({
+				grid = [[
+			( ( ^1 )0 )0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+			})
+			-- be sure that reaching root $0 exits.
+			exec_lua("ls.jump(1) ls.jump(1) ls.jump(-1)")
+			screen:expect({
+				grid = [[
+			( ( 1 )0 )^0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+			})
+		end
+	)
+	it("exit_roots = false stays in the root node but exits child.", function()
+		exec_lua([[
+			ls.setup({
+				exit_roots = false
+			})
+			ls.add_snippets("all", {
+			s("aa", { t{"( "}, i(1, "1"), t{" )"}, i(0, "0") })
+			})
+		]])
+
+		feed("iaa")
+		exec_lua("ls.expand()")
+		screen:expect({
+			grid = [[
+			( ^1 )0                                            |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+		})
+		-- screen:snapshot_util()
+		feed("aa")
+		exec_lua("ls.expand()")
+		screen:expect({
+			grid = [[
+			( ( ^1 )0 )0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+		})
+		-- do not exit when reaching to a child root
+		exec_lua("ls.jump(1) ls.jump(-1)")
+		screen:expect({
+			grid = [[
+			( ( ^1 )0 )0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+		})
+		-- root $0 does not exit.
+		exec_lua("ls.jump(1) ls.jump(1) ls.jump(-1)")
+		screen:expect({
+			grid = [[
+			( ^({3: 1 )0} )0                                       |
+			{0:~                                                 }|
+			{2:-- SELECT --}                                      |]],
+		})
+		-- new root snippet exits earlier root.
+		exec_lua("ls.jump(1)")
+		feed("aa")
+		exec_lua("ls.expand()")
+		exec_lua("ls.jump(-1) ls.jump(-1)")
+		screen:expect({
+			grid = [[
+			( ( 1 )0 )^( 1 )0                                  |
+			{0:~                                                 }|
+			{2:-- INSERT --}                                      |]],
+		})
+	end)
+
 	it("focus correctly adjusts gravities of parent-snippets.", function()
 		exec_lua([[
 			ls.setup{