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, 30 insertions, 0 deletions

diff --git a/test/functional/api/extmark_spec.lua b/test/functional/api/extmark_spec.lua
index 0a286965f2..2acfbfc949 100644
--- a/test/functional/api/extmark_spec.lua
+++ b/test/functional/api/extmark_spec.lua
@@ -1798,6 +1798,36 @@ describe('API/extmarks', function()
     eq(1, #extmarks)
     eq('https://example.com', extmarks[1][4].url)
   end)
+
+  it('respects priority', function()
+    screen = Screen.new(15, 10)
+    screen:attach()
+
+    set_extmark(ns, marks[1], 0, 0, {
+      hl_group = 'Comment',
+      end_col = 2,
+      priority = 20,
+    })
+
+    -- Extmark defined after first extmark but has lower priority, first extmark "wins"
+    set_extmark(ns, marks[2], 0, 0, {
+      hl_group = 'String',
+      end_col = 2,
+      priority = 10,
+    })
+
+    screen:expect {
+      grid = [[
+      {1:12}34^5          |
+      {2:~              }|*8
+                     |
+    ]],
+      attr_ids = {
+        [1] = { foreground = Screen.colors.Blue1 },
+        [2] = { foreground = Screen.colors.Blue1, bold = true },
+      },
+    }
+  end)
 end)
 
 describe('Extmarks buffer api with many marks', function()