Introduce colour blending utility

When making terminal-friendly interfaces, it is easy to run into the
limits of 4-bit ANSI colouring. This is easily seen when trying to show
selections or highlighting, and a shaded background is required. Without
knowing if the terminal is light or dark, and what shades its ANSI
colours are, it is not possible to pick an appropriate colour.

To generate appropriate colours, some form of blending is required.
Instead of encouraging packages to just pick a colour, or do ad-hoc
blending themselves, it makes sense for us to provide a single colour
blending function that does a good job: here, by transforming the sRGB
colour into OKLab space to do the blending in, and then back to sRGB at
the end. This extra work pays off in markedly better results.

While terminal colour detection and retheming is left for later, this
work together with the base colours lays the foundation for consistently
appropriate colouring.

Author: tecosaur

docs/src/index.md

@@ -341,4 +341,5 @@ StyledStrings.SimpleColor
 StyledStrings.parse(::Type{StyledStrings.SimpleColor}, ::String)
 StyledStrings.tryparse(::Type{StyledStrings.SimpleColor}, ::String)
 StyledStrings.merge(::StyledStrings.Face, ::StyledStrings.Face)
+StyledStrings.blend(::StyledStrings.SimpleColor, ::StyledStrings.SimpleColor, ::Real)
 ```

docs/src/internals.md

@@ -8,6 +8,8 @@ opening a pull request or issue to discuss making them part of the public API.
 ```@docs
 StyledStrings.ANSI_4BIT_COLORS
 StyledStrings.FACES
+StyledStrings.MAX_COLOR_FORWARDS
+StyledStrings.UNRESOLVED_COLOR_FALLBACK
 StyledStrings.Legacy.ANSI_256_COLORS
 StyledStrings.Legacy.NAMED_COLORS
 StyledStrings.Legacy.RENAMED_COLORS
@@ -16,13 +18,14 @@ StyledStrings.Legacy.load_env_colors!
 StyledStrings.ansi_4bit
 StyledStrings.face!
 StyledStrings.getface
+StyledStrings.load_customisations!
 StyledStrings.loadface!
 StyledStrings.loaduserfaces!
 StyledStrings.resetfaces!
+StyledStrings.rgbcolor
 StyledStrings.termcolor
 StyledStrings.termcolor24bit
 StyledStrings.termcolor8bit
-StyledStrings.load_customisations!
 ```
 
 ## Styled Markup parsing

src/StyledStrings.jl

@@ -9,7 +9,7 @@ using Base.ScopedValues: ScopedValue, with, @with
 export AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations, annotate!, annotatedstring
 
 export @styled_str
-public Face, addface!, withfaces, styled, SimpleColor
+public Face, addface!, withfaces, styled, SimpleColor, blend
 
 include("faces.jl")
 include("io.jl")

src/faces.jl

@@ -752,3 +752,111 @@ function Base.convert(::Type{Face}, spec::Dict{String,Any})
              Symbol[]
          end)
 end
+
+## Color utils ##
+
+"""
+    UNRESOLVED_COLOR_FALLBACK
+
+The fallback `RGBTuple` used when asking for a color that is not defined.
+"""
+const UNRESOLVED_COLOR_FALLBACK = (r = 0xff, g = 0x00, b = 0xff) # Pink
+
+"""
+    MAX_COLOR_FORWARDS
+
+The maximum number of times to follow color references when resolving a color.
+"""
+const MAX_COLOR_FORWARDS = 12
+
+"""
+    rgbcolor(color::Union{Symbol, SimpleColor})
+
+Resolve a `color` to an `RGBTuple`.
+
+The resolution follows these steps:
+1. If `color` is a `SimpleColor` holding an `RGBTuple`, that is returned.
+2. If `color` names a face, the face's foreground color is used.
+3. If `color` names a base color, that color is used.
+4. Otherwise, `UNRESOLVED_COLOR_FALLBACK` (bright pink) is returned.
+"""
+function rgbcolor(name::Symbol)
+    for _ in 1:MAX_COLOR_FORWARDS # Do this instead of a while loop to prevent cyclic lookups
+        fg = get(FACES.current[], name, Face()).foreground
+        isnothing(fg) && break
+        fg.value isa RGBTuple && return fg.value
+        name = fg.value
+    end
+    get(FACES.basecolors, name, UNRESOLVED_COLOR_FALLBACK)
+end
+
+function rgbcolor(color::SimpleColor)
+    val = color.value
+    if val isa RGBTuple
+        val
+    else
+        rgbcolor(val)
+    end
+end
+
+"""
+    blend(a::Union{Symbol, SimpleColor}, b::Union{Symbol, SimpleColor}, α::Real)
+
+Blend colors `a` and `b` in Oklab space, with mix ratio `α` (0–1).
+
+The colors `a` and `b` can either be `SimpleColor`s, or `Symbol`s naming a face
+or base color. The mix ratio `α` combines `(1 - α)` of `a` with `α` of `b`.
+
+# Examples
+
+```julia-repl
+julia> blend(SimpleColor(0xff0000), SimpleColor(0x0000ff), 0.5)
+SimpleColor(■ #8b54a1)
+
+julia> blend(:red, :yellow, 0.7)
+SimpleColor(■ #d47f24)
+
+julia> blend(:green, SimpleColor(0xffffff), 0.3)
+SimpleColor(■ #74be93)
+```
+"""
+function blend(c1::SimpleColor, c2::SimpleColor, α::Real)
+    function oklab(rgb::RGBTuple)
+        r, g, b = (Tuple(rgb) ./ 255) .^ 2.2
+        l = cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+        m = cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+        s = cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+        L = 0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s
+        a = 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s
+        b = 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s
+        (; L, a, b)
+    end
+    function rgb((; L, a, b))
+        tohex(v) = round(UInt8, min(255.0, 255 * max(0.0, v)^(1 / 2.2)))
+        l = (L + 0.3963377774 * a + 0.2158037573 * b)^3
+        m = (L - 0.1055613458 * a - 0.0638541728 * b)^3
+        s = (L - 0.0894841775 * a - 1.2914855480 * b)^3
+        r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s
+        g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s
+        b = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s
+        (r = tohex(r), g = tohex(g), b = tohex(b))
+    end
+    lab1 = oklab(rgbcolor(c1))
+    lab2 = oklab(rgbcolor(c2))
+    mix = (L = (1 - α) * lab1.L + α * lab2.L,
+           a = (1 - α) * lab1.a + α * lab2.a,
+           b = (1 - α) * lab1.b + α * lab2.b)
+    SimpleColor(rgb(mix))
+end
+
+function blend(f1::Union{Symbol, SimpleColor}, f2::Union{Symbol, SimpleColor}, α::Real)
+    function face_or_color(name::Symbol)
+        c = getface(name).foreground
+        if c.value === :foreground && haskey(FACES.basecolors, name)
+            c = SimpleColor(name)
+        end
+        c
+    end
+    face_or_color(c::SimpleColor) = c
+    blend(face_or_color(f1), face_or_color(f2), α)
+end

src/io.jl

@@ -92,8 +92,6 @@ function termcolor24bit(io::IO, color::RGBTuple, category::Char)
           string(color.b), 'm')
 end
 
-const MAX_COLOR_FORWARDS = 12
-
 """
     termcolor(io::IO, color::SimpleColor, category::Char)
 
@@ -311,32 +309,20 @@ Base.AnnotatedDisplay.show_annot(io::IO, ::MIME"text/html", s::Union{<:Annotated
 
 function htmlcolor(io::IO, color::SimpleColor, background::Bool = false)
     default = getface()
-    if color.value isa Symbol
-        if background && color.value == :background
-            print(io, "initial")
-        elseif !background && color.value == :foreground
-            print(io, "initial")
-        elseif (fg = get(FACES.current[], color.value, default).foreground) != SimpleColor(color.value)
-            htmlcolor(io, fg)
-        elseif haskey(FACES.basecolors, color.value)
-            htmlcolor(io, SimpleColor(FACES.basecolors[color.value]))
-        else
-            print(io, "inherit")
-        end
-    elseif background && color.value == default.background
-        htmlcolor(io, SimpleColor(:background), true)
-    elseif !background && color.value ==default.foreground
-        htmlcolor(io, SimpleColor(:foreground))
-    else
-        (; r, g, b) = color.value
-        print(io, '#')
-        r < 0x10 && print(io, '0')
-        print(io, string(r, base=16))
-        g < 0x10 && print(io, '0')
-        print(io, string(g, base=16))
-        b < 0x10 && print(io, '0')
-        print(io, string(b, base=16))
+    if background && color.value ∈ (:background, default.background)
+        return print(io, "initial")
+    elseif !background && color.value ∈ (:foreground, default.foreground)
+        return print(io, "initial")
     end
+    (; r, g, b) = rgbcolor(color)
+    default = getface()
+    print(io, '#')
+    r < 0x10 && print(io, '0')
+    print(io, string(r, base=16))
+    g < 0x10 && print(io, '0')
+    print(io, string(g, base=16))
+    b < 0x10 && print(io, '0')
+    print(io, string(b, base=16))
 end
 
 const HTML_WEIGHT_MAP = Dict{Symbol, Int}(

test/runtests.jl

@@ -571,7 +571,7 @@ end
     @test sprint(StyledStrings.htmlcolor, SimpleColor(:black)) == "#1c1a23"
     @test sprint(StyledStrings.htmlcolor, SimpleColor(:green)) == "#25a268"
     @test sprint(StyledStrings.htmlcolor, SimpleColor(:warning)) == "#e5a509"
-    @test sprint(StyledStrings.htmlcolor, SimpleColor(:nonexistant)) == "initial"
+    @test sprint(StyledStrings.htmlcolor, SimpleColor(:nonexistant)) == "#ff00ff"
     @test sprint(StyledStrings.htmlcolor, SimpleColor(0x40, 0x63, 0xd8)) == "#4063d8"
     function html_change(; attrs...)
         face = getface(Face(; attrs...))
@@ -609,7 +609,7 @@ end
         <span style=\"color: #803d9b\">`</span><span style=\"color: #25a268\">AnnotatedString</span><span style=\"color: #803d9b\">`</span> \
         <a href=\"https://en.wikipedia.org/wiki/Type_system\">type</a> to provide a <span style=\"text-decoration: #a51c2c wavy underline\">\
         full-fledged</span> textual <span style=\"font-weight: 700; color: #adbdf8; background-color: #4063d8; text-decoration: line-through\">\
-        styling</span> system, suitable for <span style=\"color: initial; background-color: #000000\">terminal</span> and graphical displays."
+        styling</span> system, suitable for <span style=\"color: #ffffff; background-color: #000000\">terminal</span> and graphical displays."
 end
 
 @testset "Legacy" begin