feat(extmarks): subpriorities (relative to declaration order) (#27131)

The "priority" field of extmarks can be used to set priorities of
extmarks which dictates which highlight group a range will actually have
when there are multiple extmarks applied. However, when multiple
extmarks have the same priority, the only way to enforce an actual
priority is through the order in which the extmarks are set.

It is not always possible or desirable to set extmarks in a specific
order, however, so we add a new "subpriority" field that explicitly
enforces the ordering of extmarks that have the same priority.

For now this will be used only to enforce priority of treesitter
highlights. A single node in a treesitter tree may match multiple
captures, in which case that node will have multiple extmarks set. The
order in which captures are returned from the treesitter API is not
_necessarily_ in the same order they are defined in a query file, so we
use the new subpriority field to force that ordering.

For now subpriorites are not documented and are not meant to be used by
external code, and it only applies to ephemeral extmarks. We indicate
the "private" nature of subpriorities by prefixing the field name with
an "_".

1 files changed, 42 insertions, 1 deletions

diff --git a/test/functional/ui/decorations_spec.lua b/test/functional/ui/decorations_spec.lua
index 7b3533454c..cb804f056d 100644
--- a/test/functional/ui/decorations_spec.lua
+++ b/test/functional/ui/decorations_spec.lua
@@ -687,7 +687,7 @@ describe('decorations providers', function()
     ]]}
   end)
 
-   it('can add new providers during redraw #26652', function()
+  it('can add new providers during redraw #26652', function()
     setup_provider [[
     local ns = api.nvim_create_namespace('test_no_add')
     function on_do(...)
@@ -697,6 +697,47 @@ describe('decorations providers', function()
 
     helpers.assert_alive()
   end)
+
+  it('supports subpriorities (order of definitions in a query file #27131)', function()
+    insert(mulholland)
+    setup_provider [[
+      local test_ns = api.nvim_create_namespace('mulholland')
+      function on_do(event, ...)
+        if event == "line" then
+          local win, buf, line = ...
+          api.nvim_buf_set_extmark(buf, test_ns, line, 0, {
+            end_row = line + 1,
+            hl_eol = true,
+            hl_group = 'Comment',
+            ephemeral = true,
+            priority = 100,
+            _subpriority = 20,
+          })
+
+          -- This extmark is set last but has a lower subpriority, so the first extmark "wins"
+          api.nvim_buf_set_extmark(buf, test_ns, line, 0, {
+            end_row = line + 1,
+            hl_eol = true,
+            hl_group = 'String',
+            ephemeral = true,
+            priority = 100,
+            _subpriority = 10,
+          })
+        end
+      end
+    ]]
+
+    screen:expect{grid=[[
+      {4:// just to see if there was an accident }|
+      {4:// on Mulholland Drive                  }|
+      {4:try_start();                            }|
+      {4:bufref_T save_buf;                      }|
+      {4:switch_buffer(&save_buf, buf);          }|
+      {4:posp = getmark(mark, false);            }|
+      {4:restore_buffer(&save_buf);^              }|
+                                              |
+    ]]}
+  end)
 end)
 
 local example_text = [[