feat: heading width based on level

## Details

Request: #126

The `heading -> width` option is now allowed to be `block`, `width`, or
an array of these 2 values. If it is an array we index into it using a
clamp based on the heading level.

Requires a new kind of validation logic but not too bad, seems to cover
all cases. Also required moving list class to generics, which was easy.
Move all union strings to type alias annotations so exact values can be
defined once and reused as needed.

Author: MeanderingProgrammer

README.md

@@ -247,6 +247,8 @@ require('render-markdown').setup({
         -- Width of the heading background:
         --  block: width of the heading text
         --  full: full width of the window
+        -- Can also be an array of the above values in which case the 'level' is used
+        -- to index into the array using a clamp
         width = 'full',
         -- Amount of padding to add to the left of headings
         left_pad = 0,
@@ -544,6 +546,8 @@ require('render-markdown').setup({
         -- Width of the heading background:
         --  block: width of the heading text
         --  full: full width of the window
+        -- Can also be an array of the above values in which case the 'level' is used
+        -- to index into the array using a clamp
         width = 'full',
         -- Amount of padding to add to the left of headings
         left_pad = 0,

doc/render-markdown.txt

@@ -276,6 +276,8 @@ Full Default Configuration ~
             -- Width of the heading background:
             --  block: width of the heading text
             --  full: full width of the window
+            -- Can also be an array of the above values in which case the 'level' is used
+            -- to index into the array using a clamp
             width = 'full',
             -- Amount of padding to add to the left of headings
             left_pad = 0,
@@ -573,6 +575,8 @@ Wiki Page
             -- Width of the heading background:
             --  block: width of the heading text
             --  full: full width of the window
+            -- Can also be an array of the above values in which case the 'level' is used
+            -- to index into the array using a clamp
             width = 'full',
             -- Amount of padding to add to the left of headings
             left_pad = 0,

lua/render-markdown/handler/markdown.lua

@@ -89,6 +89,10 @@ function Handler:heading(info)
     local level = str.width(info.text)
     local foreground = list.clamp(heading.foregrounds, level)
     local background = list.clamp(heading.backgrounds, level)
+    local heading_width = heading.width
+    if type(heading_width) == 'table' then
+        heading_width = list.clamp(heading_width, level)
+    end
 
     local icon_width = self:heading_icon(info, level, foreground, background)
     if heading.sign then
@@ -102,8 +106,8 @@ function Handler:heading(info)
         hl_eol = true,
     })
 
-    local width = self:heading_width(info, icon_width)
-    if heading.width == 'block' then
+    local width = self:heading_width(info, heading_width, icon_width)
+    if heading_width == 'block' then
         -- Overwrite anything beyond width with Normal
         self:add(true, info.start_row, 0, {
             priority = 0,
@@ -165,11 +169,12 @@ end
 
 ---@private
 ---@param info render.md.NodeInfo
+---@param heading_width render.md.heading.Width
 ---@param icon_width integer
 ---@return integer
-function Handler:heading_width(info, icon_width)
+function Handler:heading_width(info, heading_width, icon_width)
     local heading = self.config.heading
-    if heading.width == 'block' then
+    if heading_width == 'block' then
         local width = heading.left_pad + icon_width + heading.right_pad
         local content = info:sibling('inline')
         if content ~= nil then

lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local M = {}
 
 ---@private
 ---@type string
-M.version = '6.0.10'
+M.version = '6.0.11'
 
 function M.check()
     vim.health.start('render-markdown.nvim [version]')

lua/render-markdown/init.lua

@@ -38,10 +38,13 @@ local M = {}
 ---@field public highlight? string
 ---@field public custom? table<string, render.md.UserLinkComponent>
 
+---@alias render.md.table.Style 'full'|'normal'|'none'
+---@alias render.md.table.Cell 'padded'|'raw'|'overlay'
+
 ---@class (exact) render.md.UserPipeTable
 ---@field public enabled? boolean
----@field public style? 'full'|'normal'|'none'
----@field public cell? 'padded'|'raw'|'overlay'
+---@field public style? render.md.table.Style
+---@field public cell? render.md.table.Cell
 ---@field public border? string[]
 ---@field public alignment_indicator? string
 ---@field public head? string
@@ -82,29 +85,37 @@ local M = {}
 ---@field public width? 'full'|integer
 ---@field public highlight? string
 
+---@alias render.md.code.Style 'full'|'normal'|'language'|'none'
+---@alias render.md.code.Position 'left'|'right'
+---@alias render.md.code.Width 'full'|'block'
+---@alias render.md.code.Border 'thin'|'thick'
+
 ---@class (exact) render.md.UserCode
 ---@field public enabled? boolean
 ---@field public sign? boolean
----@field public style? 'full'|'normal'|'language'|'none'
----@field public position? 'left'|'right'
+---@field public style? render.md.code.Style
+---@field public position? render.md.code.Position
 ---@field public disable_background? string[]
----@field public width? 'full'|'block'
+---@field public width? render.md.code.Width
 ---@field public left_pad? integer
 ---@field public right_pad? integer
 ---@field public min_width? integer
----@field public border? 'thin'|'thick'
+---@field public border? render.md.code.Border
 ---@field public above? string
 ---@field public below? string
 ---@field public highlight? string
 ---@field public highlight_inline? string
 
+---@alias render.md.heading.Position 'overlay'|'inline'
+---@alias render.md.heading.Width 'full'|'block'
+
 ---@class (exact) render.md.UserHeading
 ---@field public enabled? boolean
 ---@field public sign? boolean
----@field public position? 'overlay'|'inline'
+---@field public position? render.md.heading.Position
 ---@field public icons? string[]
 ---@field public signs? string[]
----@field public width? 'full'|'block'
+---@field public width? render.md.heading.Width|(render.md.heading.Width)[]
 ---@field public left_pad? integer
 ---@field public right_pad? integer
 ---@field public min_width? integer
@@ -139,12 +150,15 @@ local M = {}
 ---@field public sign? render.md.UserSign
 ---@field public win_options? table<string, render.md.UserWindowOption>
 
+---@alias render.md.config.Preset 'none'|'lazy'|'obsidian'
+---@alias render.md.config.LogLevel 'debug'|'error'
+
 ---@class (exact) render.md.UserConfig: render.md.UserBufferConfig
----@field public preset? 'none'|'lazy'|'obsidian'
+---@field public preset? render.md.config.Preset
 ---@field public markdown_query? string
 ---@field public markdown_quote_query? string
 ---@field public inline_query? string
----@field public log_level? 'debug'|'error'
+---@field public log_level? render.md.config.LogLevel
 ---@field public file_types? string[]
 ---@field public acknowledge_conflicts? boolean
 ---@field public latex? render.md.UserLatex
@@ -257,6 +271,8 @@ M.default_config = {
         -- Width of the heading background:
         --  block: width of the heading text
         --  full: full width of the window
+        -- Can also be an array of the above values in which case the 'level' is used
+        -- to index into the array using a clamp
         width = 'full',
         -- Amount of padding to add to the left of headings
         left_pad = 0,

lua/render-markdown/list.lua

@@ -27,19 +27,21 @@ function M.add_mark(marks, conceal, start_row, start_col, opts)
     return true
 end
 
----@param values string[]
+---@generic T
+---@param values T[]
 ---@param index integer
----@return string?
+---@return T?
 function M.cycle(values, index)
     if #values == 0 then
         return nil
     end
     return values[((index - 1) % #values) + 1]
 end
 
----@param values string[]
+---@generic T
+---@param values T[]
 ---@param index integer
----@return string
+---@return T
 function M.clamp(values, index)
     assert(#values >= 1, 'Must have at least one value')
     return values[math.min(index, #values)]

lua/render-markdown/logger.lua

@@ -29,7 +29,7 @@ function log.reset()
     log.entries = {}
 end
 
----@param level string
+---@param level render.md.config.LogLevel
 ---@param name string
 ---@param message any
 function log.add(level, name, message)

lua/render-markdown/parser/pipe_table.lua

@@ -4,9 +4,11 @@ local logger = require('render-markdown.logger')
 ---@class render.md.parser.PipeTable
 local M = {}
 
+---@alias render.md.table.Alignment 'left'|'right'|'center'|'default'
+
 ---@class render.md.parsed.TableColumn
 ---@field width integer
----@field alignment 'left'|'right'|'center'|'default'
+---@field alignment render.md.table.Alignment
 
 ---@class render.md.parsed.PipeTable
 ---@field head render.md.NodeInfo
@@ -86,7 +88,7 @@ end
 
 ---@private
 ---@param cell render.md.NodeInfo
----@return 'left'|'right'|'center'|'default'
+---@return render.md.table.Alignment
 function M.parse_alignment(cell)
     local align_left = cell:child('pipe_table_align_left') ~= nil
     local align_right = cell:child('pipe_table_align_right') ~= nil

lua/render-markdown/state.lua

@@ -7,7 +7,7 @@ local configs = {}
 ---@class render.md.State
 ---@field private config render.md.Config
 ---@field enabled boolean
----@field log_level 'debug'|'error'
+---@field log_level render.md.config.LogLevel
 ---@field file_types string[]
 ---@field acknowledge_conflicts boolean
 ---@field latex render.md.Latex
@@ -106,6 +106,37 @@ function M.validate()
         }
     end
 
+    ---@param value any
+    ---@param valid_values string[]
+    ---@param nilable boolean
+    ---@return vim.validate.Spec
+    local function one_or_array_of(value, valid_values, nilable)
+        local description = 'one or array of ' .. vim.inspect(valid_values)
+        if nilable then
+            description = description .. ' or nil'
+        end
+        return {
+            value,
+            function(v)
+                if v == nil then
+                    return nilable
+                elseif type(v) == 'string' then
+                    return vim.tbl_contains(valid_values, v)
+                elseif type(v) == 'table' then
+                    for i, item in ipairs(v) do
+                        if not vim.tbl_contains(valid_values, item) then
+                            return false, string.format('Index %d is %s', i, item)
+                        end
+                    end
+                    return true
+                else
+                    return false
+                end
+            end,
+            description,
+        }
+    end
+
     ---@param value string[]
     ---@param nilable boolean
     ---@return vim.validate.Spec
@@ -119,15 +150,15 @@ function M.validate()
             function(v)
                 if v == nil then
                     return nilable
-                elseif type(v) ~= 'table' then
-                    return false
-                else
+                elseif type(v) == 'table' then
                     for i, item in ipairs(v) do
                         if type(item) ~= 'string' then
                             return false, string.format('Index %d is %s', i, type(item))
                         end
                     end
                     return true
+                else
+                    return false
                 end
             end,
             description,
@@ -168,7 +199,7 @@ function M.validate()
                 position = one_of(heading.position, { 'overlay', 'inline' }, {}, nilable),
                 icons = string_array(heading.icons, nilable),
                 signs = string_array(heading.signs, nilable),
-                width = one_of(heading.width, { 'full', 'block' }, {}, nilable),
+                width = one_or_array_of(heading.width, { 'full', 'block' }, nilable),
                 left_pad = { heading.left_pad, 'number', nilable },
                 right_pad = { heading.right_pad, 'number', nilable },
                 min_width = { heading.min_width, 'number', nilable },

lua/render-markdown/types.lua

@@ -29,8 +29,8 @@
 
 ---@class (exact) render.md.PipeTable
 ---@field public enabled boolean
----@field public style 'full'|'normal'|'none'
----@field public cell 'padded'|'raw'|'overlay'
+---@field public style render.md.table.Style
+---@field public cell render.md.table.Cell
 ---@field public border string[]
 ---@field public alignment_indicator string
 ---@field public head string
@@ -74,14 +74,14 @@
 ---@class (exact) render.md.Code
 ---@field public enabled boolean
 ---@field public sign boolean
----@field public style 'full'|'normal'|'language'|'none'
----@field public position 'left'|'right'
+---@field public style render.md.code.Style
+---@field public position render.md.code.Position
 ---@field public disable_background string[]
----@field public width 'full'|'block'
+---@field public width render.md.code.Width
 ---@field public left_pad integer
 ---@field public right_pad integer
 ---@field public min_width integer
----@field public border 'thin'|'thick'
+---@field public border render.md.code.Border
 ---@field public above string
 ---@field public below string
 ---@field public highlight string
@@ -90,10 +90,10 @@
 ---@class (exact) render.md.Heading
 ---@field public enabled boolean
 ---@field public sign boolean
----@field public position 'overlay'|'inline'
+---@field public position render.md.heading.Position
 ---@field public icons string[]
 ---@field public signs string[]
----@field public width 'full'|'block'
+---@field public width render.md.heading.Width|(render.md.heading.Width)[]
 ---@field public left_pad integer
 ---@field public right_pad integer
 ---@field public min_width integer
@@ -129,11 +129,11 @@
 ---@field public win_options table<string, render.md.WindowOption>
 
 ---@class (exact) render.md.Config: render.md.BufferConfig
----@field public preset 'none'|'lazy'|'obsidian'
+---@field public preset render.md.config.Preset
 ---@field public markdown_query string
 ---@field public markdown_quote_query string
 ---@field public inline_query string
----@field public log_level 'debug'|'error'
+---@field public log_level render.md.config.LogLevel
 ---@field public file_types string[]
 ---@field public acknowledge_conflicts boolean
 ---@field public latex render.md.Latex