feat: avoid inline text for checkboxes when possible

## Details

Request: #378

Previously checkboxes were rendered by concealing the underlying text
and inlining the icon as virtual text. This works but would mess with
the cursor positions while scrolling due to how neovim handles showing
and hiding inline virtual text.

To avoid this we now use information about the amount of space available
to us, i.e. the width of the text in square brackets compared to the
width of the icon we are rendering, to add more clever marks.

Only when the icon is larger than the space available do we do the same
thing as before and fully conceal + inline.

Otherwise we use overlay virtual text to show the icon and conceal any
underlying text that extends under the icon (if any). When doing this we
also take into account the new `checkbox.right_pad` option (default
value 1), and similarly attempt to use the space available for the
padding. If the padding extends outside the available space then the
remaining amount is added as inline virtual text, requires neovim >=
`0.10.0` to work. The default value of 1 is chosen so that the rendered
text looks identical in most cases to before, since we now treat the
space after the checkbox as space available to us.

### Related Impacts

To maintain parity with how checked and unchecked checkboxes are handled
by `markdown`, we now require that there is a space following custom
states. This allows us to better determine exactly how much space we
have to work with.

The `checkbox.position` configuration option was removed. We now infer
how to display checkboxes best based on the space available to us and
the icon we are about to show. Any potential differences in how things
are displayed, can likely be changed back by using the new
`checkbox.right_pad` option. Most users should not see any differences.
Any users of `checkbox.position` should simply remove it from their
configuration, keeping it is fine, it just doesn't do anything.

Custom checkbox states will now work for versions of neovim older than
`0.10.0`, but since the plugin as a whole still requires `0.9.0` at a
minimum this only adds a couple supported versions for that specific
feature, and there are some limitations to its usage.

Author: MeanderingProgrammer

Diff for: README.md

@@ -32,7 +32,7 @@ Plugin to improve viewing Markdown files in Neovim
   - Code inline: background
   - Horizontal breaks: icon, color, width
   - List bullets: icon, color, padding [^1]
-  - Checkboxes: icon, color, user defined states [^1]
+  - Checkboxes: icon, color, user defined states
   - Block quotes: icon, color, line breaks [^1]
   - Callouts: icon, color, user defined values, Github & Obsidian defaults
   - Tables: border, color, alignment indicator, auto align cells [^1]
@@ -494,10 +494,8 @@ require('render-markdown').setup({
         enabled = true,
         -- Additional modes to render checkboxes.
         render_modes = false,
-        -- Determines how icons fill the available space.
-        -- | inline  | underlying text is concealed resulting in a left aligned icon |
-        -- | overlay | result is left padded with spaces to hide any additional text |
-        position = 'inline',
+        -- Padding to add to the right of checkboxes.
+        right_pad = 1,
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'.
             icon = '󰄱 ',
@@ -1086,10 +1084,8 @@ require('render-markdown').setup({
         enabled = true,
         -- Additional modes to render checkboxes.
         render_modes = false,
-        -- Determines how icons fill the available space.
-        -- | inline  | underlying text is concealed resulting in a left aligned icon |
-        -- | overlay | result is left padded with spaces to hide any additional text |
-        position = 'inline',
+        -- Padding to add to the right of checkboxes.
+        right_pad = 1,
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'.
             icon = '󰄱 ',

Diff for: benches/readme_spec.lua

@@ -4,7 +4,7 @@ local util = require('benches.util')
 
 describe('README.md', function()
     it('default', function()
-        local base_marks = 114
+        local base_marks = 113
         util.less_than(util.setup('README.md'), 60)
         util.num_marks(base_marks)
 

Diff for: doc/render-markdown.txt

@@ -62,7 +62,7 @@ Plugin to improve viewing Markdown files in Neovim
     - Code inline: background
     - Horizontal breaks: icon, color, width
     - List bullets: icon, color, padding 
-    - Checkboxes: icon, color, user defined states 
+    - Checkboxes: icon, color, user defined states
     - Block quotes: icon, color, line breaks 
     - Callouts: icon, color, user defined values, Github & Obsidian defaults
     - Tables: border, color, alignment indicator, auto align cells 
@@ -559,10 +559,8 @@ Default Configuration ~
             enabled = true,
             -- Additional modes to render checkboxes.
             render_modes = false,
-            -- Determines how icons fill the available space.
-            -- | inline  | underlying text is concealed resulting in a left aligned icon |
-            -- | overlay | result is left padded with spaces to hide any additional text |
-            position = 'inline',
+            -- Padding to add to the right of checkboxes.
+            right_pad = 1,
             unchecked = {
                 -- Replaces '[ ]' of 'task_list_marker_unchecked'.
                 icon = '󰄱 ',
@@ -1139,10 +1137,8 @@ Checkbox Configuration ~
             enabled = true,
             -- Additional modes to render checkboxes.
             render_modes = false,
-            -- Determines how icons fill the available space.
-            -- | inline  | underlying text is concealed resulting in a left aligned icon |
-            -- | overlay | result is left padded with spaces to hide any additional text |
-            position = 'inline',
+            -- Padding to add to the right of checkboxes.
+            right_pad = 1,
             unchecked = {
                 -- Replaces '[ ]' of 'task_list_marker_unchecked'.
                 icon = '󰄱 ',

Diff for: lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '8.1.9'
+M.version = '8.1.10'
 
 function M.check()
     M.start('version')

Diff for: lua/render-markdown/init.lua

@@ -163,10 +163,8 @@ local M = {}
 ---@field highlight? string
 ---@field scope_highlight? string
 
----@alias render.md.checkbox.Position 'overlay'|'inline'
-
 ---@class (exact) render.md.UserCheckbox: render.md.UserBaseComponent
----@field position? render.md.checkbox.Position
+---@field right_pad? integer
 ---@field unchecked? render.md.UserCheckboxComponent
 ---@field checked? render.md.UserCheckboxComponent
 ---@field custom? table<string, render.md.UserCustomCheckbox>
@@ -285,6 +283,7 @@ local M = {}
 ---| 'sign'
 
 ---@alias render.md.config.conceal.Ignore table<render.md.Element, render.md.Modes>
+---@alias render.md.mark.Element boolean|render.md.Element
 
 ---@class (exact) render.md.UserAntiConceal
 ---@field enabled? boolean
@@ -656,10 +655,8 @@ M.default_config = {
         enabled = true,
         -- Additional modes to render checkboxes.
         render_modes = false,
-        -- Determines how icons fill the available space.
-        -- | inline  | underlying text is concealed resulting in a left aligned icon |
-        -- | overlay | result is left padded with spaces to hide any additional text |
-        position = 'inline',
+        -- Padding to add to the right of checkboxes.
+        right_pad = 1,
         unchecked = {
             -- Replaces '[ ]' of 'task_list_marker_unchecked'.
             icon = '󰄱 ',

Diff for: lua/render-markdown/lib/list.lua

@@ -29,7 +29,7 @@ function Marks:get()
     return self.marks
 end
 
----@param element boolean|render.md.Element
+---@param element render.md.mark.Element
 ---@param node render.md.Node
 ---@param opts render.md.MarkOpts
 ---@param offset? Range4
@@ -41,7 +41,7 @@ function Marks:add_over(element, node, opts, offset)
     return self:add(element, node.start_row + offset[1], node.start_col + offset[2], opts)
 end
 
----@param element boolean|render.md.Element
+---@param element render.md.mark.Element
 ---@param start_row integer
 ---@param start_col integer
 ---@param opts render.md.MarkOpts
@@ -71,7 +71,7 @@ function Marks:add(element, start_row, start_col, opts)
 end
 
 ---@private
----@param element boolean|render.md.Element
+---@param element render.md.mark.Element
 ---@return boolean
 function Marks:conceal(element)
     if type(element) == 'boolean' then

Diff for: lua/render-markdown/lib/node.lua

@@ -191,4 +191,10 @@ function Node:lines()
     return vim.api.nvim_buf_get_lines(self.buf, self.start_row, self.end_row, false)
 end
 
+---@return string?
+function Node:after()
+    local row, col = self.end_row, self.end_col
+    return vim.api.nvim_buf_get_text(self.buf, row, col, row, col + 1, {})[1]
+end
+
 return Node

Diff for: lua/render-markdown/render/base.lua

@@ -46,7 +46,51 @@ function Base:sign(enabled, text, highlight)
 end
 
 ---@protected
----@param element boolean|render.md.Element
+---@param icon string
+---@param highlight string
+---@return boolean
+function Base:check_icon(icon, highlight)
+    local line = self:append({}, icon, highlight)
+    local space = self.context:width(self.node) + 1 - Str.width(icon)
+    local right_pad = self.config.checkbox.right_pad
+    if space < 0 then
+        -- Not enough space to fit the icon in-place
+        return self.marks:add_over('check_icon', self.node, {
+            virt_text = self:append(line, right_pad),
+            virt_text_pos = 'inline',
+            conceal = '',
+        }, { 0, 0, 0, 1 })
+    else
+        local fits = math.min(space, right_pad)
+        self:append(line, fits)
+        space, right_pad = space - fits, right_pad - fits
+        local row = self.node.start_row
+        local start_col, end_col = self.node.start_col, self.node.end_col + 1
+        self.marks:add('check_icon', row, start_col, {
+            end_col = end_col - space,
+            virt_text = line,
+            virt_text_pos = 'overlay',
+        })
+        if space > 0 then
+            -- Hide extra space after the icon
+            self.marks:add('check_icon', row, end_col - space, {
+                end_col = end_col,
+                conceal = '',
+            })
+        end
+        if right_pad > 0 then
+            -- Add padding
+            self.marks:add('check_icon', row, end_col, {
+                virt_text = self:append({}, right_pad),
+                virt_text_pos = 'inline',
+            })
+        end
+        return true
+    end
+end
+
+---@protected
+---@param element render.md.mark.Element
 ---@param node render.md.Node?
 ---@param highlight? string
 function Base:scope(element, node, highlight)

Diff for: lua/render-markdown/render/checkbox.lua

@@ -1,47 +1,32 @@
 local Base = require('render-markdown.render.base')
-local Str = require('render-markdown.lib.str')
 
 ---@class render.md.render.Checkbox: render.md.Renderer
 ---@field private checkbox render.md.CheckboxComponent
----@field private inline boolean
 local Render = setmetatable({}, Base)
 Render.__index = Render
 
 ---@return boolean
 function Render:setup()
-    local checkbox = self.config.checkbox
-    if self.context:skip(checkbox) then
+    local config = self.config.checkbox
+    if self.context:skip(config) then
         return false
     end
 
-    local type_mapping = {
-        task_list_marker_unchecked = checkbox.unchecked,
-        task_list_marker_checked = checkbox.checked,
+    local types = {
+        task_list_marker_unchecked = config.unchecked,
+        task_list_marker_checked = config.checked,
     }
-    self.checkbox = type_mapping[self.node.type]
+    self.checkbox = types[self.node.type]
     if self.checkbox == nil then
         return false
     end
 
-    self.inline = checkbox.position == 'inline'
-
     return true
 end
 
 function Render:render()
-    self:icon()
+    self:check_icon(self.checkbox.icon, self.checkbox.highlight)
     self:scope('check_scope', self.node:sibling('paragraph'), self.checkbox.scope_highlight)
 end
 
----@private
-function Render:icon()
-    local icon = self.checkbox.icon
-    local text = self.inline and icon or Str.pad_to(self.node.text, icon) .. icon
-    self.marks:add_over('check_icon', self.node, {
-        virt_text = { { text, self.checkbox.highlight } },
-        virt_text_pos = self.inline and 'inline' or 'overlay',
-        conceal = self.inline and '' or nil,
-    })
-end
-
 return Render

Diff for: lua/render-markdown/render/list_item.lua

@@ -90,7 +90,7 @@ function Render:hide_marker()
 end
 
 ---@private
----@param element boolean|render.md.Element
+---@param element render.md.mark.Element
 ---@param highlight string?
 function Render:highlight_scope(element, highlight)
     self:scope(element, self.node:child('paragraph'), highlight)

Diff for: lua/render-markdown/render/shortcut.lua

@@ -75,19 +75,11 @@ end
 ---@private
 ---@param checkbox render.md.CustomCheckbox
 function Render:checkbox(checkbox)
-    if self.context:skip(self.config.checkbox) then
+    local config = self.config.checkbox
+    if self.context:skip(config) or self.node:after() ~= ' ' then
         return
     end
-
-    local inline = self.config.checkbox.position == 'inline'
-    local icon, highlight = checkbox.rendered, checkbox.highlight
-    local text = inline and icon or Str.pad_to(self.node.text, icon) .. icon
-    local added = self.marks:add_over('check_icon', self.node, {
-        virt_text = { { text, highlight } },
-        virt_text_pos = 'inline',
-        conceal = '',
-    })
-
+    local added = self:check_icon(checkbox.rendered, checkbox.highlight)
     if added then
         self.context:add_checkbox(self.node.start_row, checkbox)
     end

Diff for: lua/render-markdown/state.lua

@@ -31,7 +31,6 @@ function M.setup(default_config, user_config)
     -- Override settings that require neovim >= 0.10.0 and have compatible alternatives
     if not util.has_10 then
         config.code.position = 'right'
-        config.checkbox.position = 'overlay'
     end
     -- Use lazy.nvim file type configuration if available and no user value is specified
     if user_config.file_types == nil then
@@ -216,7 +215,7 @@ function M.validate()
             end)
             :nested('checkbox', function(checkbox)
                 component_rules(checkbox)
-                    :one_of('position', { 'overlay', 'inline' })
+                    :type('right_pad', 'number')
                     :nested({ 'unchecked', 'checked' }, function(box)
                         box:type({ 'icon', 'highlight' }, 'string'):type('scope_highlight', { 'string', 'nil' }):check()
                     end)

Diff for: lua/render-markdown/types.lua

@@ -115,7 +115,7 @@
 ---@field scope_highlight? string
 
 ---@class (exact) render.md.Checkbox: render.md.BaseComponent
----@field position render.md.checkbox.Position
+---@field right_pad integer
 ---@field unchecked render.md.CheckboxComponent
 ---@field checked render.md.CheckboxComponent
 ---@field custom table<string, render.md.CustomCheckbox>

Diff for: tests/box_dash_quote_spec.lua

@@ -13,24 +13,30 @@ describe('box_dash_quote.md', function()
             :add(row:get(), row:get(), 0, 1, util.heading.icon(1))
             :add(row:get(), row:inc(), 0, 0, util.heading.bg(1))
 
-        marks:add(row:inc(), row:get(), 0, 2, util.conceal())
-        marks:add(row:get(), row:get(), 2, 5, {
-            virt_text = { { '󰄱 ', 'RmUnchecked' } },
-            virt_text_pos = 'inline',
-            conceal = '',
-        })
-        marks:add(row:inc(), row:get(), 0, 2, util.conceal())
-        marks:add(row:get(), row:get(), 2, 5, {
-            virt_text = { { '󰱒 ', 'RmChecked' } },
-            virt_text_pos = 'inline',
-            conceal = '',
-        })
-        marks:add(row:inc(), row:get(), 0, 2, util.conceal())
-        marks:add(row:get(), row:get(), 2, 5, {
-            virt_text = { { '󰥔 ', 'RmTodo' } },
-            virt_text_pos = 'inline',
-            conceal = '',
-        })
+        marks
+            :add(row:inc(), row:get(), 0, 2, util.conceal())
+            :add(row:get(), row:get(), 2, 5, {
+                virt_text = { { '󰄱 ', 'RmUnchecked' }, { ' ', 'Normal' } },
+                virt_text_pos = 'overlay',
+            })
+            :add(row:get(), row:get(), 5, 6, util.conceal())
+        marks
+            :add(row:inc(), row:get(), 0, 2, util.conceal())
+            :add(row:get(), row:get(), 2, 5, {
+                virt_text = { { '󰱒 ', 'RmChecked' }, { ' ', 'Normal' } },
+                virt_text_pos = 'overlay',
+            })
+            :add(row:get(), row:get(), 5, 6, util.conceal())
+        marks
+            :add(row:inc(), row:get(), 0, 2, util.conceal())
+            :add(row:get(), row:get(), 2, 6, {
+                virt_text = { { '󰥔 ', 'RmTodo' } },
+                virt_text_pos = 'overlay',
+            })
+            :add(row:get(), nil, 6, nil, {
+                virt_text = { { ' ', 'Normal' } },
+                virt_text_pos = 'inline',
+            })
         marks:add(row:inc(), row:get(), 0, 2, util.bullet(1))
 
         marks:add(row:inc(2), nil, 0, nil, {