Module:Color

---

local utilsError = require("Module:UtilsError")
local utilsString = require("Module:UtilsString")

local data = mw.loadData("Module:Color/Data")

local p = {}

local CAT_DEPRECATED_COLORS = "Category:Articles Using Deprecated Colors"

function p.Main(frame)
	local args = frame:getParent().args
	return p.color(args[1], args[2])
end

function p.List(frame)
	local args = frame:getParent().args
	return p.listColors(args[1])
end

-- There is intentationally duplicated code at [[Module:Cite]] - see [[wikipedia:Rule of three]]
function p.color(colorId, text)
	local colorData = data.colors[colorId]
	-- Backwards compatibility for inputting hex codes directly
	-- We shouldn't allow this in articles anymore but we can keep support on user and talk pages to avoid breaking user signatures
	if colorData == nil and utilsString.startsWith(colorId, "#") and (mw.title.getCurrentTitle().isTalkPage or mw.title.getCurrentTitle().nsText == "User") then
		html = mw.html.create("span")
			:css("color", colorId)
			:wikitext(text)
		return tostring(html)
	elseif colorData == nil then
		utilsError.warn(string.format("<code>%s</code> is not a valid color name. See [[Template:Color]] for the list of supported colors.", colorId))
		return text .. "[[Category:Articles Using Invalid Arguments in Template Calls]]"
	end
	local colorValue = colorData.color
	local html = mw.html.create("span")
		:addClass("colored-text")
		:addClass("colored-text-highlight") -- to distinguish from the colored-text added by [[Module:Color]]
		:wikitext(text)
	if utilsString.startsWith(colorValue, "linear-gradient") then
		-- It's OK to use inline styles here because the color is a "fixed" part of the quote and applies to all Zelda Wiki skins
		-- This enables colors to be defined in one place in module data, which is easier to maintain
		html:css({
			["background-image"] = colorValue,
			["color"] = "transparent",
			["background-clip"] = "text",
			["-webkit-background-clip"] = "text"
		})
	else
		html:css("color", colorValue)
	end
	local result = tostring(html)
	if colorData.deprecated then
		utilsError.warn(string.format("Color <code>%s</code> is being discontinued. Please update it to a current color listed at [[Template:Color]].", colorId))
		result = result.."[["..CAT_DEPRECATED_COLORS.."]]"
	end
	return result
end

-- lists colors for one game, or all games if game is nil
function p.listColors(game)
	-- Perfomance optimization; only loading dependencies on the documentation pages where they're needed
	local Franchise = require("Module:Franchise")
	local utilsLayout = require("Module:UtilsLayout")
	local utilsString = require("Module:UtilsString")
	local utilsTable = require("Module:UtilsTable")
	
	local tableRows = {
		{
			header = true,
			{
				content = "Color",
				styles = {
					width = "150px"
				},
			},
			"Name",
			"Notes",
		}
	}
	local games = game and {game} or Franchise.enum()
	local listAllGames = game == nil
	local colorKeys = utilsTable.keys(data.colors)
	for _, game in ipairs(games) do -- "game" here could also be a book like Encyclopedia
		-- The added " " is for doing a whole-word match. e,g. SS should match "SS Green" but not "SSHD Green"
		local gameColorKeys = utilsTable.filter(colorKeys, utilsString._startsWith(game .. " "))
		table.sort(gameColorKeys)
		if listAllGames and #gameColorKeys > 0 then
			table.insert(tableRows, {
				header = true,
				{
					colspan = 3,
					content = Franchise.display(game),
				}
			})
		end
		for _, colorKey in ipairs(gameColorKeys) do
			local colorData = data.colors[colorKey]
			if not colorData.deprecated then
				table.insert(tableRows, {
					{
						content = " ", -- using whitespace so the cell isn't treated as being empty by utilsLayout
						styles = {
							["background"] = colorData.color,
						}
					},
					"<b><code>"..colorKey.."</code></b>",
					colorData.notes or ""
				})
			end
		end
	end
	return utilsLayout.table({
		caption = "Text Colors",
		rows = tableRows,
		hideEmptyColumns = true,
	})
end

-- For auto-generated doc at Module:Colors/Data/Documentation
function p.Data()
	return p.listColors()
end

p.Templates = {
	["Color"] = {
		purpose = "This template allows text to be colored such that quotes from games (e.g. [[Template:Cite]]) or other media have the same color highlights as the source text. These colors convey meaningful empasis and are essential to Zelda Wiki's [[Guidelines:Terminology|terminology guidelines]].",
		format = "inline",
		params = {
			[1] = {
				name = "color",
				required = true,
				type = "string",
				desc = "The name of the color - see supported colors below"
			},
			[2] = {
				name = "text",
				required = true,
				type = "string",
				desc = "The text to color"
			}
		},
		examples = {
			{"TWWHD Vermilion", "merchant's oath"},
			{"SSHD Fi Blue", "Demise"},
			{"invalid color", "foo"},
			{"deprecated color", "bar"},
		}
	},
	["Color/List"] = {
		purpose = "This template lists the colors that [[Template:Color]] supports.",
		format = "inline",
		params = {
			[1] = {
				name = "game",
				type = "string",
				enum = {
					reference = "[[Data:Franchise]]" 
				},
				desc = "If specified, the template will output the colors for the given game only. Otherwise, all colors will be listed.",
				canOmit = true,
			}
		},
		examples = {
			{"BotW"},
			{"E"},
		}
	}
}

-- For auto-generated doc at Module:Colors/Data/Documentation
p.Schemas = {
	Data = {
		type = "record",
		required = true,
		properties = {
			{
				name = "colors",
				required = true,
				type = "map",
				keys = {
					type = "string",
				},
				values = {
					type = "record",
					properties = {
						{
							name = "color",
							required = true,
							type = "string",
							desc = "A [https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color hex color] (with preceding #) or a [https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient linear-gradient].",
						},
						{
							name = "notes",
							type = "string",
							desc = "Anything that editors should know about the color – the context in which it appears, other colors it could be confused with, etc.",
						},
						{
							name = "deprecated",
							type = "boolean",
							desc = "Set this to true for colors that are to be removed or replaced. Pages using this color are added to [[:"..CAT_DEPRECATED_COLORS.."]].<br/>Please indicate in <code>notes</code> what color should be used instead."
						}
					}
				}
			}
		}
	}
}

return p