feat: support empty lists for all heading properties

## Details

Requst: #202

Adjust `list.clamp` to handle empty lists and return nil much like `list.cycle`.
This allows the following heading properties to now be empty:

- foregrounds
- backgrounds
- width
- left_margin
- left_pad
- right_pad
- min_width

For the following properties an empty list just functions like the default value:

- width
- left_margin
- left_pad
- right_pad
- min_width

This leaves foregrounds & backgrounds which are specially handled as follows:

- Without a foreground `signs` use only sign highlight
- Icons will use the values availble, if none are an icon will not be rendered
- If no background is available rendering a background (block & full) will be skipped
- Border lines will use spaces if a highlight is not available
- Left padding will use the padding highlight instead of the background when missing

Minor refactor to dynamic highlight, `inverse` -> `bg_to_fg`.

Author: MeanderingProgrammer

lua/render-markdown/colors.lua

@@ -1,9 +1,9 @@
 ---@class render.md.cache.Colors
 ---@field combine table<string, { fg: string, bg: string }>
----@field inverse table<string, { hl: string }>
+---@field bg_to_fg table<string, { hl: string }>
 local Cache = {
     combine = {},
-    inverse = {},
+    bg_to_fg = {},
 }
 
 ---@class render.md.Colors
@@ -71,8 +71,8 @@ function M.reload()
     for _, color in pairs(Cache.combine) do
         M.combine(color.fg, color.bg, true)
     end
-    for _, color in pairs(Cache.inverse) do
-        M.inverse_bg(color.hl, true)
+    for _, color in pairs(Cache.bg_to_fg) do
+        M.bg_to_fg(color.hl, true)
     end
 end
 
@@ -100,16 +100,16 @@ end
 ---@param highlight string
 ---@param force? boolean
 ---@return string
-function M.inverse_bg(highlight, force)
-    local name = string.format('%s_Inverse_%s', M.prefix, highlight)
-    if Cache.inverse[name] == nil or force then
+function M.bg_to_fg(highlight, force)
+    local name = string.format('%s_bgtofg_%s', M.prefix, highlight)
+    if Cache.bg_to_fg[name] == nil or force then
         local hl = M.get_hl(highlight)
         vim.api.nvim_set_hl(0, name, {
             fg = hl.bg,
             ---@diagnostic disable-next-line: undefined-field
             ctermfg = hl.ctermbg,
         })
-        Cache.inverse[name] = { hl = highlight }
+        Cache.bg_to_fg[name] = { hl = highlight }
     end
     return name
 end

lua/render-markdown/core/list.lua

@@ -55,7 +55,7 @@ end
 ---@generic T
 ---@param values T[]
 ---@param index integer
----@return T?
+---@return T|nil
 function M.cycle(values, index)
     if #values == 0 then
         return nil
@@ -66,11 +66,14 @@ end
 ---@generic T
 ---@param values `T`|T[]
 ---@param index integer
----@return T
+---@return T|nil
 function M.clamp(values, index)
     if type(values) == 'table' then
-        assert(#values >= 1, 'Must have at least one value')
-        return values[math.min(index, #values)]
+        if #values == 0 then
+            return nil
+        else
+            return values[math.min(index, #values)]
+        end
     else
         return values
     end

lua/render-markdown/health.lua

@@ -4,7 +4,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '7.3.3'
+M.version = '7.3.4'
 
 function M.check()
     M.start('version')

lua/render-markdown/render/base.lua

@@ -27,15 +27,19 @@ end
 
 ---@protected
 ---@param text? string
----@param highlight string
+---@param highlight? string
 function Base:sign(text, highlight)
     local sign = self.config.sign
     if not sign.enabled or text == nil then
         return
     end
+    local sign_highlight = sign.highlight
+    if highlight ~= nil then
+        sign_highlight = colors.combine(highlight, sign_highlight)
+    end
     self.marks:add(false, self.info.start_row, self.info.start_col, {
         sign_text = text,
-        sign_hl_group = colors.combine(highlight, sign.highlight),
+        sign_hl_group = sign_highlight,
     })
 end
 

lua/render-markdown/render/code.lua

@@ -154,7 +154,7 @@ function Render:background(icon_added)
             if self.data.margin > 0 then
                 table.insert(virt_text, { str.pad(self.data.margin), self.config.padding.highlight })
             end
-            table.insert(virt_text, { icon:rep(width - self.data.col), colors.inverse_bg(self.code.highlight) })
+            table.insert(virt_text, { icon:rep(width - self.data.col), colors.bg_to_fg(self.code.highlight) })
             self.marks:add(true, row, self.data.col, {
                 virt_text = virt_text,
                 virt_text_pos = 'overlay',

lua/render-markdown/render/heading.lua

@@ -9,8 +9,8 @@ local str = require('render-markdown.core.str')
 ---@field level integer
 ---@field icon? string
 ---@field sign? string
----@field foreground string
----@field background string
+---@field foreground? string
+---@field background? string
 ---@field width render.md.heading.Width
 ---@field left_margin number
 ---@field left_pad number
@@ -59,11 +59,11 @@ function Render:setup()
         sign = list.cycle(self.heading.signs, level),
         foreground = list.clamp(self.heading.foregrounds, level),
         background = list.clamp(self.heading.backgrounds, level),
-        width = list.clamp(self.heading.width, level),
-        left_margin = list.clamp(self.heading.left_margin, level),
-        left_pad = list.clamp(self.heading.left_pad, level),
-        right_pad = list.clamp(self.heading.right_pad, level),
-        min_width = list.clamp(self.heading.min_width, level),
+        width = list.clamp(self.heading.width, level) or 'full',
+        left_margin = list.clamp(self.heading.left_margin, level) or 0,
+        left_pad = list.clamp(self.heading.left_pad, level) or 0,
+        right_pad = list.clamp(self.heading.right_pad, level) or 0,
+        min_width = list.clamp(self.heading.min_width, level) or 0,
         end_row = self.info.end_row + (atx and 1 or 0),
     }
 
@@ -84,10 +84,16 @@ end
 ---@private
 ---@return integer
 function Render:icon()
-    local icon, highlight = self.data.icon, { self.data.foreground, self.data.background }
+    local icon, highlight = self.data.icon, {}
+    if self.data.foreground ~= nil then
+        table.insert(highlight, self.data.foreground)
+    end
+    if self.data.background ~= nil then
+        table.insert(highlight, self.data.background)
+    end
 
     if not self.data.atx then
-        if icon == nil then
+        if icon == nil or #highlight == 0 then
             return 0
         end
         local added = true
@@ -107,7 +113,7 @@ function Render:icon()
     -- `#` characters, one is added to account for the space after the last `#` but before
     -- the  heading title, and concealed text is subtracted since that space is not usable
     local width = self.data.level + 1 - self.context:concealed(self.info)
-    if icon == nil then
+    if icon == nil or #highlight == 0 then
         return width
     end
 
@@ -157,6 +163,10 @@ end
 ---@private
 ---@param width render.md.width.Heading
 function Render:background(width)
+    local highlight = self.data.background
+    if highlight == nil then
+        return
+    end
     local win_col, padding = 0, {}
     if self.data.width == 'block' then
         win_col = width.margin + width.content + self:indent(self.data.level)
@@ -165,7 +175,7 @@ function Render:background(width)
     for row = self.info.start_row, self.data.end_row - 1 do
         self.marks:add(true, row, 0, {
             end_row = row + 1,
-            hl_group = self.data.background,
+            hl_group = highlight,
             hl_eol = true,
         })
         if win_col > 0 and #padding > 0 then
@@ -187,18 +197,29 @@ function Render:border(width)
         return
     end
 
-    local foreground, background = self.data.foreground, colors.inverse_bg(self.data.background)
+    local foreground = self.data.foreground
+    local background = self.data.background and colors.bg_to_fg(self.data.background)
     local prefix = self.heading.border_prefix and self.data.level or 0
     local virtual = self.heading.border_virtual
 
     ---@param icon string
     ---@return { [1]: string, [2]: string }[]
     local function line(icon)
+        ---@param size integer
+        ---@param highlight? string
+        ---@return { [1]: string, [2]: string }
+        local function section(size, highlight)
+            if highlight ~= nil then
+                return { icon:rep(size), highlight }
+            else
+                return { str.pad(size), self.config.padding.highlight }
+            end
+        end
         return {
-            { str.pad(width.margin), self.config.padding.highlight },
-            { icon:rep(width.padding), background },
-            { icon:rep(prefix), foreground },
-            { icon:rep(width.content - width.padding - prefix), background },
+            section(width.margin, nil),
+            section(width.padding, background),
+            section(prefix, foreground),
+            section(width.content - width.padding - prefix, background),
         }
     end
 
@@ -241,12 +262,15 @@ end
 ---@param width render.md.width.Heading
 function Render:left_pad(width)
     local virt_text = {}
-    if width.margin > 0 then
-        table.insert(virt_text, { str.pad(width.margin), self.config.padding.highlight })
-    end
-    if width.padding > 0 then
-        table.insert(virt_text, { str.pad(width.padding), self.data.background })
+    ---@param size integer
+    ---@param highlight? string
+    local function append(size, highlight)
+        if size > 0 then
+            table.insert(virt_text, { str.pad(size), highlight or self.config.padding.highlight })
+        end
     end
+    append(width.margin, nil)
+    append(width.padding, self.data.background)
     if #virt_text > 0 then
         for row = self.info.start_row, self.data.end_row - 1 do
             self.marks:add(false, row, 0, {

tests/indent_spec.lua

@@ -22,7 +22,7 @@ end
 ---@return render.md.MarkInfo
 local function border(row, level, position)
     local foreground = util.hl(string.format('H%d', level))
-    local background = util.hl_inverse(string.format('H%dBg', level))
+    local background = util.hl_bg_to_fg(string.format('H%dBg', level))
     local icon = position == 'above' and '▄' or '▀'
     local line = {
         { '', 'Normal' },

tests/util.lua

@@ -275,7 +275,7 @@ function M.code_below(row, col, width)
     return {
         row = { row },
         col = { col },
-        virt_text = { { string.rep('▀', width), M.hl_inverse('Code') } },
+        virt_text = { { string.rep('▀', width), M.hl_bg_to_fg('Code') } },
         virt_text_pos = 'overlay',
     }
 end
@@ -408,8 +408,8 @@ end
 
 ---@param base string
 ---@return string
-function M.hl_inverse(base)
-    return M.hl('_Inverse_' .. M.hl(base))
+function M.hl_bg_to_fg(base)
+    return M.hl('_bgtofg_' .. M.hl(base))
 end
 
 ---@param suffix string