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 any valid HTML color
	-- In articles we should only allow defined game colors, but we can keep support for any HTML color on user and talk pages to avoid breaking user signatures that use the template this way
	if colorData == nil and (mw.title.getCurrentTitle().isTalkPage or mw.title.getCurrentTitle().nsText == "User" or mw.title.getCurrentTitle().nsText == "Zelda Wiki") 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({includeCompilations = true})
	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