Module:CrossRef

Shared helper that renders cross-reference link lists between categories.

Library module shipped by the publishing bot; shared across categories. Bot-published — edits are overwritten on re-publish.

---

-- Module:CrossRef — renders the `cross_refs` field as labelled bullet lists.
-- Public API: CrossRef.renderAll(rec, labelOrder).
-- API contract:
--   rec.cross_refs = { ["<label>"] = { {slug, name, icon}, ... }, ... }
--   labelOrder     = list of label strings; missing labels are silently skipped.
-- Maintainer don'ts: never recompute a slug here; ref.slug is set by flatten.py
-- from the plan's slug_rule. This module renders [[ref.slug|ref.name]] verbatim.

local p = {}

-- Render a single labelled section: '== <label> ==' followed by a
-- bullet list of '* [[<slug>|<name>]]' lines. Returns '' on empty
-- so the caller can concat without an extra newline check.
function p.renderSection(label, refs)
  if not refs or #refs == 0 then return '' end
  local out = {'', '== ' .. label .. ' =='}
  for _, ref in ipairs(refs) do
    local slug = ref.slug or ref.name or '?'
    local name = ref.name or ref.slug or '?'
    local icon = ref.icon
    if icon and icon ~= '' then
      table.insert(out, '* [[File:' .. icon .. '|24px|link=' .. slug
        .. ']] [[' .. slug .. '|' .. name .. ']]')
    else
      table.insert(out, '* [[' .. slug .. '|' .. name .. ']]')
    end
  end
  return table.concat(out, '\n')
end

-- Render every section listed in `order` (a list of label strings)
-- for which rec.cross_refs has a non-empty entry. Sections appear in
-- the order the caller declared; unknown labels are skipped silently.
function p.renderAll(rec, order)
  local refs_map = (rec and rec.cross_refs) or {}
  if not order or #order == 0 then
    -- Best-effort fallback: render in iteration order (stable enough
    -- for spot checks; production callers pass an explicit order).
    local out = {}
    for label, refs in pairs(refs_map) do
      local section = p.renderSection(label, refs)
      if section ~= '' then table.insert(out, section) end
    end
    return table.concat(out, '\n')
  end
  local out = {}
  for _, label in ipairs(order) do
    local section = p.renderSection(label, refs_map[label])
    if section ~= '' then table.insert(out, section) end
  end
  return table.concat(out, '\n')
end

return p