Modulo:Materialize colors examples

-- This module was created to generate the examples in this page:
--   [[Template:Materialize colors]]
--   https://it.wikipedia.org/wiki/Template:Materialize_colors
--
-- CODE STYLE:
--   We are trying to make the module easy to be shared in other wikis so without external dependencies.
--   To be updated, import the version from:
--        [[w:it:Modulo:Materialize_colors_examples]]
--        https://it.wikipedia.org/wiki/Modulo:Materialize_colors_examples

---
--- LOCAL FUNCTIONS
---

---
-- Remove empty elements from a table
--
-- @param  args table
-- @return table
local function cleanWikitextArguments( args )
	local result = {}
	for k, v in pairs( args ) do

		-- eventually trim
		if type( v ) == 'string' then

			v = mw.text.trim( v )

			-- promote to nil
			if v == '' then
				v = nil	
			end
		end
		if v then
			result[ k ] = v
		end
	end
	return result
end

---
-- Array replace
--
-- This somehow emulates the PHP array_replace()
--
-- @param table..
-- @return table
--
local function arrayReplace( ... )

	-- final table
	local complete = {}

	-- table with all the arguments
	local args = { ... }

	-- for each table
	for _, arg in pairs( args ) do

		-- merge all the consecutive tables in the complete one
		for k, v in pairs( arg ) do

			-- the most left value takes precedence
			complete[ k ] = v
		end
	end

	return complete
end


---
-- Merge some frame arguments
--
-- @return table
local function frameArguments( frame )
	local argsParent = cleanWikitextArguments( frame:getParent().args or {} )
	local args       = cleanWikitextArguments( frame.args )
	return arrayReplace( args, argsParent )
end


--- Add a space in front of a CSS class
-- @param a
-- @param b string or nil
-- @return string
local function addStartingSpace( a )
	local s = a or ""
	if s ~= "" then
		s = " " .. s
	end
	return s
end

--- Concat two CSS classes with a space
-- @param a string or nil
-- @param b string or nil
-- @return string
local function concatClasses( a, b )
	local s = a or ""
	return s .. addStartingSpace( b )
end

--
-- CLASSES
--

---
-- Simple class describing a MaterialFlavor (e.g. "darken-2")
---
local MaterialFlavor = {}
MaterialFlavor.__index = MaterialFlavor

---
-- Simple class describing a MaterialColorFlavor (e.g. "red darken-2")
---
local MaterialColorFlavor = {}
MaterialColorFlavor.__index = MaterialColorFlavor

---
-- Simple class describing a MaterialColor (e.g. "red")
---
local MaterialColor = {}
MaterialColor.__index = MaterialColor

---
--- METHODS
---

---
-- Constructor for a MaterialFlavor
-- @param name base of the color flavor (e.g. "darken" for "darken-2")
-- @param i numeric index of the color flavor (e.g. 2 for "darken-2")
-- @param isDark whenever it's a dark flavor (e.g. true if it needs white text)
-- @return MaterialFlavor
function MaterialFlavor:new( base, i, isDark )
	local name = base
	if i then
		name = name .. "-" .. i
	end
	local materialFlavor = {
		base   = base,
		i      = i,
		name   = name,
		isDark = isDark or false,
	}
	setmetatable( materialFlavor, MaterialFlavor )
	return materialFlavor
end

---
-- Constructor for a MaterialColorFlavor
-- @param color name of the color e.g. 'red'
-- @param flavor reference to a MaterialFlavor
-- @return MaterialColorFlavor
function MaterialColorFlavor:new( color, flavor )
	local materialColorFlavor = {
		color  = color,
		flavor = flavor,
	}
	setmetatable( materialColorFlavor, MaterialColorFlavor )
	return materialColorFlavor
end

---
-- Get the CSS class name for the text
-- @return string
function MaterialColorFlavor:getTextCSSClass()
	return self.flavor.isDark and 'white-text' or nil
end

---
-- Constructor for a MaterialColorFlavor
-- @param color name of the color e.g. 'red'
-- @param flavor reference to a MaterialFlavor
-- @return string
function MaterialColorFlavor:getContainerCSSClass()
	local s = self.color
	if self.flavor.name then
		s = s .. " " .. self.flavor.name
	end
	return s
end

---
-- Get the container's CSS class, plus the text class (if any)
-- @param color name of the color e.g. 'red'
-- @param flavor reference to a MaterialFlavor
-- @return string
function MaterialColorFlavor:getContainerCSSClassAndTextClass()
	return concatClasses(
		self:getContainerCSSClass(),
		self:getTextCSSClass()
	)
end

--- Constructor for a MaterialColor
-- @param color name of the color e.g. 'red'
-- @param skipAccent whenever to skip the "accents" flavor
function MaterialColor:new( color, skipAccent )

	-- no color no party
	if color == nil then
		error( "missing color name (e.g. red)" )
	end

	local materialColor = {
		color  = color,
		skip   = {
			accent = skipAccent or true and false,
		},
	}
	setmetatable( materialColor, MaterialColor )
	return materialColor
end

--- Do something for each color flavor
-- @param doSomething Your custom function - the first argument will be a MaterialColorFlavor
function MaterialColor:eachColorFlavor( flavors, doSomething )
	for i, flavor in pairs( flavors ) do
		if not self.skip[ flavor.base ] then
			doSomething( MaterialColorFlavor:new( self.color, flavor ) )
		end
	end
end

--- Create an HTML palette (a stack of colorized divs)
function MaterialColor:createPaletteHTML( flavors, containerClass )
	local s = ""
	local APIX = "\""

	containerClass = addStartingSpace( containerClass )

	-- for each color flavor, create some HTML
	self:eachColorFlavor( flavors, function( flavor )
		s = s .. "<div class=" .. APIX
			-- start HTML class name:
			.. flavor:getContainerCSSClassAndTextClass()
			.. containerClass
			.. APIX .. ">"
			 -- displayed text:
			.. flavor:getContainerCSSClass()
			.. "</div>\n"
	end )

	return s
end

-- create a new package
local p = {}

-- save a color flavor
function p._newFlavor( base, i, isDark )
	-- index by desired order
	p._KNOWN_FLAVORS[ #p._KNOWN_FLAVORS +1 ] = MaterialFlavor:new( base, i, isDark )
end

-- save a color by its name
function p._newColor( color, skipAccent )
	-- index by name
	p._KNOWN_COLORS_BY_NAME[ color ] = MaterialColor:new( color, skipAccent )

	-- index by desired order
	p._KNOWN_COLORS_BY_ORDER[ #p._KNOWN_COLORS_BY_ORDER + 1 ] = p._KNOWN_COLORS_BY_NAME[ color ]
end

---
--- INITIALIZATION
---

--- a complete array of generic color flavors
p._KNOWN_FLAVORS = {}
p._newFlavor( "lighten", 5       )
p._newFlavor( "lighten", 4       )
p._newFlavor( "lighten", 3       )
p._newFlavor( "lighten", 2       )
p._newFlavor( nil      , nil     ) -- yup, the default color without flavor
p._newFlavor( "darken" , 1, true ) -- dark version with white text
p._newFlavor( "darken" , 2, true )
p._newFlavor( "darken" , 3, true )
p._newFlavor( "darken" , 4, true )
p._newFlavor( "accent" , 1       )
p._newFlavor( "accent" , 2       )
p._newFlavor( "accent" , 3       )
p._newFlavor( "accent" , 4       )

--- a complete array of known colors indexed by name
p._KNOWN_COLORS_BY_ORDER = {}
p._KNOWN_COLORS_BY_NAME = {}
p._newColor( "red"               )
p._newColor( "pink"              )
p._newColor( "purple"            )
p._newColor( "deep-purple"       )
p._newColor( "indigo"            )
p._newColor( "blue"              )
p._newColor( "light-blue"        )
p._newColor( "cyan"              )
p._newColor( "teal"              )
p._newColor( "green"             )
p._newColor( "light-green"       )
p._newColor( "lime"              )
p._newColor( "yellow"            )
p._newColor( "amber"             )
p._newColor( "orange"            )
p._newColor( "deep-orange"       )
p._newColor( "brown"      , true ) -- no "accent"
p._newColor( "grey"       , true ) -- no "accent"
p._newColor( "blue-grey"  , true ) -- no "accent"

---
--- CORE FUNCTIONS
---

-- get a color by its name
function p._getColor( name )
	return p._KNOWN_COLORS_BY_NAME[ name ] or error( "unknown color" )	
end

--- Generate an HTML color palette
-- This function should be called from Lua
function p._paletteHTML( args )
	args = args or {}

	-- arguments
	local color          = args.color
	local containerClass = args.containerClass

	-- find the color and generate the HTML palette
	return p._getColor( color )
		:createPaletteHTML( p._KNOWN_FLAVORS, containerClass )
end

--- Generate an HTML color palette
-- This function should be called from wikitext
function p.paletteHTML( frame )
	local args = frameArguments( frame )
	return p._paletteHTML( args )
end

--- Generate an HTML color palette
-- This function should be called from Lua
function p._paletteHTML( args )

	-- arguments
	args = args or {}
	local color          = args.color
	local containerClass = args.containerClass

	-- find the color and generate the HTML palette
	return p._getColor( color )
		:createPaletteHTML( p._KNOWN_FLAVORS, containerClass )
end

--- Generate an HTML color palette
-- This function should be called from wikitext
function p.paletteHTML( frame )
	local args = frameArguments( frame )
	return p._paletteHTML( args )
end

--- Generate an HTML color palette
-- This function should be called from Lua
function p._allPalettesHTML( args )

	local s = ""

	-- arguments
	args = args or {}
	local containerClass = args.containerClass
	local containerPre   = args.containerPre  or ''
	local containerPost  = args.containerPost or ''

	-- generate all palettes
	for i, color in pairs( p._KNOWN_COLORS_BY_ORDER ) do
		s = s .. containerPre
		s = s .. color:createPaletteHTML( p._KNOWN_FLAVORS, containerClass )
		s = s .. containerPost
	end

	-- find the color and generate the HTML palette
	return s
end

--- Generate an HTML color palette
-- This function should be called from wikitext
function p.allPalettesHTML( frame )
	local args = frameArguments( frame )
	return p._allPalettesHTML( args )
end

-- return the package
return p