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

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 = '󰄱 ',

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)
 

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 = '󰄱 ',

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')

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 = '󰄱 ',

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

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

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)

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

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)