refactor: replace monolithic utils.lua with focused modules (#27)

Author: mcanouil

CHANGELOG.md

@@ -2,7 +2,9 @@
 
 ## Unreleased
 
-No user-facing changes.
+### Refactoring
+
+- refactor: Replace monolithic `utils.lua` with focused modules (`string.lua`, `logging.lua`, `metadata.lua`, `pandoc-helpers.lua`, `html.lua`, `paths.lua`, `colour.lua`).
 
 ## 1.3.0 (2026-02-21)
 
@@ -67,4 +69,3 @@ No user-facing changes.
 
 ## 0.1.0 (2022-09-12)
 
-No user-facing changes.

_extensions/elevator/_modules/html.lua

@@ -0,0 +1,103 @@
+--- MC HTML - HTML generation and dependency management for Quarto Lua filters and shortcodes
+--- @module html
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+--- Load a sibling module from the same directory as this file.
+--- @param filename string The sibling module filename (e.g., 'string.lua')
+--- @return table The loaded module
+local function load_sibling(filename)
+  local source = debug.getinfo(1, 'S').source:sub(2)
+  local dir = source:match('(.*[/\\])') or ''
+  return require((dir .. filename):gsub('%.lua$', ''))
+end
+
+--- Load string module for escape_html and escape_attribute
+local str = load_sibling('string.lua')
+
+-- ============================================================================
+-- HTML RAW GENERATION UTILITIES
+-- ============================================================================
+
+--- Generates a raw HTML header element.
+--- @param level integer The header level (e.g., 2 for <h2>)
+--- @param text string|nil The header text
+--- @param id string The id attribute for the header
+--- @param classes table List of classes for the header
+--- @param attributes table|nil Additional HTML attributes
+--- @return string Raw HTML string for the header
+function M.raw_header(level, text, id, classes, attributes)
+  local attr_str = ''
+  if id and id ~= '' then
+    attr_str = attr_str .. ' id="' .. str.escape_attribute(id) .. '"'
+  end
+  if classes and #classes > 0 then
+    local escaped_classes = {}
+    for i, cls in ipairs(classes) do
+      escaped_classes[i] = str.escape_attribute(cls)
+    end
+    attr_str = attr_str .. ' class="' .. table.concat(escaped_classes, ' ') .. '"'
+  end
+  if attributes then
+    for k, v in pairs(attributes) do
+      attr_str = attr_str .. ' ' .. str.escape_attribute(k) .. '="' .. str.escape_attribute(v) .. '"'
+    end
+  end
+  return string.format('<h%d%s>%s</h%d>', level, attr_str, str.escape_html(text or ''), level)
+end
+
+-- ============================================================================
+-- HTML DEPENDENCY UTILITIES
+-- ============================================================================
+
+--- Managed HTML dependency tracker
+--- Tracks which dependencies have been added to prevent duplication
+--- @type table<string, boolean>
+local dependency_tracker = {}
+
+--- Ensure HTML dependency is added only once per document.
+--- Prevents duplicate dependency injection by tracking dependencies by name.
+--- Returns true if dependency was added, false if already present.
+---
+--- @param config table Dependency configuration with fields: name (required), version, scripts, stylesheets, head
+--- @return boolean True if dependency was added, false if already added
+--- @usage M.ensure_html_dependency({name = 'my-lib', version = '1.0.0', scripts = {'lib.js'}})
+function M.ensure_html_dependency(config)
+  if not config or not config.name then
+    error("HTML dependency configuration must include a 'name' field")
+  end
+
+  --- @type string Unique key for this dependency
+  local dep_key = config.name
+
+  -- Check if already added
+  if dependency_tracker[dep_key] then
+    return false
+  end
+
+  -- Add the dependency
+  quarto.doc.add_html_dependency(config)
+
+  -- Mark as added
+  dependency_tracker[dep_key] = true
+  return true
+end
+
+--- Reset dependency tracker.
+--- Useful for testing or when processing multiple independent documents.
+--- In normal usage, this should not be called as dependencies persist per document.
+---
+--- @return nil
+function M.reset_dependencies()
+  dependency_tracker = {}
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M

_extensions/elevator/_modules/string.lua

@@ -0,0 +1,198 @@
+--- MC String - String manipulation and escaping for Quarto Lua filters and shortcodes
+--- @module string
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+-- ============================================================================
+-- STRING UTILITIES
+-- ============================================================================
+
+--- Pandoc utility function for converting values to strings
+--- @type function
+M.stringify = pandoc.utils.stringify
+
+--- Check if a string is empty or nil.
+--- Utility function to determine if a value is empty or nil,
+--- which is useful for parameter validation throughout the module.
+--- @param s string|nil|table The value to check for emptiness
+--- @return boolean True if the value is nil or empty, false otherwise
+--- @usage local result = M.is_empty("") -- returns true
+--- @usage local result = M.is_empty(nil) -- returns true
+--- @usage local result = M.is_empty("hello") -- returns false
+function M.is_empty(s)
+  return s == nil or s == ''
+end
+
+--- Escape special pattern characters in a string for Lua pattern matching
+--- @param s string The string to escape
+--- @return string The escaped string
+--- @usage local escaped = M.escape_pattern("user/repo#123")
+function M.escape_pattern(s)
+  local escaped = s:gsub('([%^%$%(%)%%%.%[%]%*%+%-%?])', '%%%1')
+  return escaped
+end
+
+--- Split a string by a separator
+--- @param str string The string to split
+--- @param sep string The separator pattern
+--- @return table Array of string fields
+--- @usage local parts = M.split("a.b.c", ".")
+function M.split(str, sep)
+  local fields = {}
+  local pattern = string.format('([^%s]+)', sep)
+  str:gsub(pattern, function(c) fields[#fields + 1] = c end)
+  return fields
+end
+
+--- Trim leading and trailing whitespace from a string
+--- @param str string The string to trim
+--- @return string The trimmed string
+--- @usage local trimmed = M.trim("  hello world  ") -- returns "hello world"
+function M.trim(str)
+  if str == nil then return '' end
+  return str:match('^%s*(.-)%s*$')
+end
+
+--- Convert any value to a string, handling Pandoc objects and empty values.
+--- Returns nil for empty or nil values, otherwise returns a string representation.
+--- @param val any The value to convert
+--- @return string|nil The string value or nil if empty
+--- @usage local str = M.to_string(kwargs.value)
+function M.to_string(val)
+  if not val then return nil end
+  if type(val) == 'string' then
+    return val ~= '' and val or nil
+  end
+  -- Handle Pandoc objects
+  if pandoc and pandoc.utils and pandoc.utils.stringify then
+    local str = pandoc.utils.stringify(val)
+    return str ~= '' and str or nil
+  end
+  local str = tostring(val)
+  return str ~= '' and str or nil
+end
+
+-- ============================================================================
+-- ESCAPE UTILITIES
+-- ============================================================================
+
+--- Escape special LaTeX characters in text.
+--- @param text string The text to escape
+--- @return string The escaped text safe for LaTeX
+function M.escape_latex(text)
+  text = string.gsub(text, '\\', '\\textbackslash{}')
+  text = string.gsub(text, '%{', '\\{')
+  text = string.gsub(text, '%}', '\\}')
+  text = string.gsub(text, '%$', '\\$')
+  text = string.gsub(text, '%&', '\\&')
+  text = string.gsub(text, '%%', '\\%%')
+  text = string.gsub(text, '%#', '\\#')
+  text = string.gsub(text, '%^', '\\textasciicircum{}')
+  text = string.gsub(text, '%_', '\\_')
+  text = string.gsub(text, '~', '\\textasciitilde{}')
+  return text
+end
+
+--- Escape special Typst characters in text.
+--- @param text string The text to escape
+--- @return string The escaped text safe for Typst
+function M.escape_typst(text)
+  text = string.gsub(text, '%#', '\\#')
+  return text
+end
+
+--- Escape characters for Typst string literals (inside `"..."`).
+--- @param text string The text to escape
+--- @return string The escaped text safe for Typst string literals
+function M.escape_typst_string(text)
+  return text:gsub('\\', '\\\\'):gsub('"', '\\"')
+end
+
+--- Escape special Lua pattern characters for use in string.gsub.
+--- @param text string The text containing characters to escape
+--- @return string The escaped text safe for Lua patterns
+function M.escape_lua_pattern(text)
+  text = string.gsub(text, '%%', '%%%%')
+  text = string.gsub(text, '%^', '%%^')
+  text = string.gsub(text, '%$', '%%$')
+  text = string.gsub(text, '%(', '%%(')
+  text = string.gsub(text, '%)', '%%)')
+  text = string.gsub(text, '%.', '%%.')
+  text = string.gsub(text, '%[', '%%[')
+  text = string.gsub(text, '%]', '%%]')
+  text = string.gsub(text, '%*', '%%*')
+  text = string.gsub(text, '%+', '%%+')
+  text = string.gsub(text, '%-', '%%-')
+  text = string.gsub(text, '%?', '%%?')
+  return text
+end
+
+--- Escape special HTML characters in text.
+--- Escapes &, <, >, ", and ' to prevent XSS and ensure valid HTML.
+--- @param text string The text to escape
+--- @return string Escaped text safe for use in HTML
+--- @usage local escaped = M.escape_html('Hello <World>')
+function M.escape_html(text)
+  if text == nil then return '' end
+  if type(text) ~= 'string' then text = tostring(text) end
+  local result = text
+      :gsub('&', '&amp;')
+      :gsub('<', '&lt;')
+      :gsub('>', '&gt;')
+      :gsub('"', '&quot;')
+      :gsub("'", '&#39;')
+  return result
+end
+
+--- Escape special HTML attribute characters.
+--- Escapes characters that could break attribute values.
+--- @param value string The attribute value to escape
+--- @return string Escaped value safe for use in HTML attributes
+--- @usage local escaped = M.escape_attribute('Hello "World"')
+function M.escape_attribute(value)
+  if value == nil then return '' end
+  if type(value) ~= 'string' then value = tostring(value) end
+  local result = value
+      :gsub('&', '&amp;')
+      :gsub('"', '&quot;')
+      :gsub('<', '&lt;')
+      :gsub('>', '&gt;')
+  return result
+end
+
+--- Escape text for different formats.
+--- @param text string The text to escape
+--- @param format string The format to escape for (e.g., "latex", "typst", "lua")
+--- @return string The escaped text
+function M.escape_text(text, format)
+  local escape_functions = {
+    latex = M.escape_latex,
+    typst = M.escape_typst,
+    lua = M.escape_lua_pattern
+  }
+
+  local escape = escape_functions[format]
+  if escape then
+    return escape(text)
+  else
+    error('Unsupported escape format: ' .. format)
+  end
+end
+
+--- Converts a string to a valid HTML id by lowercasing and replacing spaces.
+--- @param text string The text to convert
+--- @return string The HTML id
+function M.ascii_id(text)
+  local id = text:lower():gsub('[^a-z0-9 ]', ''):gsub(' +', '-')
+  return id
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M