Modifica di 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 skip Table of flavor names to be skipped (e.g. { darken = true } to skip darken )
function MaterialColor:new( color, skip )

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

	local materialColor = {
		color  = color,
		skip   = skip or {},
	}
	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, args )
	local s = ""
	local APIX = "\""

	local colorPre  = args.colorPre  or ''
	local colorPost = args.colorPost or '\n'
	local containerClass = addStartingSpace( args.containerClass )

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

	return s
end

-- create a new package
local p = {}

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

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

---
--- CONSTANTS
---

local SKIP_ACCENTS = {
	accent  = true, -- skip flavor accent
}

local NOT_REALLY_A_COLOR = {
	accent  = true, -- skip flavor accent
	lighten = true, -- skip flavor lighten
	darken  = true, -- skip flavor darken
}

---
--- INITIALIZATION
---
-- special flavors useful for black and white
p._SPECIAL_FLAVOR_NEUTRAL = MaterialFlavor:new( nil, nil        ) -- just color, no flavor
p._SPECIAL_FLAVOR_DARK    = MaterialFlavor:new( nil, nil, true  ) -- just color, no flavor, is dark

--- a complete palette of generic color flavors
p._KNOWN_FLAVORS = {
	MaterialFlavor:new( "lighten", 5       ),
	MaterialFlavor:new( "lighten", 4       ),
	MaterialFlavor:new( "lighten", 3       ),
	MaterialFlavor:new( "lighten", 2       ),
	p._SPECIAL_FLAVOR_NEUTRAL,                -- yup, the default color without flavor
	MaterialFlavor:new( "darken" , 1, true ), -- dark version with white text
	MaterialFlavor:new( "darken" , 2, true ), -- dark version with white text
	MaterialFlavor:new( "darken" , 3, true ), -- dark version with white text
	MaterialFlavor:new( "darken" , 4, true ), -- dark version with white text
	MaterialFlavor:new( "accent" , 1       ),
	MaterialFlavor:new( "accent" , 2       ),
	MaterialFlavor:new( "accent" , 3       ),
	MaterialFlavor:new( "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"      , SKIP_ACCENTS )
p._newColor( "grey"       , SKIP_ACCENTS )
p._newColor( "blue-grey"  , SKIP_ACCENTS )

-- add other special colors
p._WHITE = MaterialColor:new( "white", NOT_REALLY_A_COLOR )
p._BLACK = MaterialColor:new( "black", NOT_REALLY_A_COLOR )

---
--- CORE FUNCTIONS
---

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

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

	-- find the color and generate the HTML palette
	return p._getColor( args.color )
		:createPaletteHTML( p._KNOWN_FLAVORS, args )
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 {}

	-- find the color and generate the HTML palette
	return p._getColor( args.color )
		:createPaletteHTML( p._KNOWN_FLAVORS, args )
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 containerPre   = args.containerPre  or ''
	local containerPost  = args.containerPost or ''

	-- generate all palettes (but not white and black)
	for i, color in pairs( p._KNOWN_COLORS_BY_ORDER ) do
		s = s .. containerPre
		s = s .. color:createPaletteHTML( p._KNOWN_FLAVORS, args )
		s = s .. containerPost
	end

	-- generate also a nice palette for white and black
	s = s .. containerPre
	s = s .. p._WHITE:createPaletteHTML( { p._SPECIAL_FLAVOR_NEUTRAL }, args )
	s = s .. p._BLACK:createPaletteHTML( { p._SPECIAL_FLAVOR_DARK    }, args )
	s = s .. containerPost

	-- 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