Align the semantics and handling of default fg/bg

tecosaur · tecosaur · commit 9bb8ffdd8c28 · 2025-10-26T12:50:19.000+08:00
The intended semantics of the default face is that it represents the
typesetting context that the AnnotatedString can expect to be placed in.
As such, when the value of a Face's fg/bg is the same as the default
value, we should take this to mean that the fg/bg can be applied by
restoring the default style (using the appropriate ANSI codes or CSS
declaration).

To model this appropriately, we can't make do with setting the default
foreground and background to ":default". Adding a :foreground and
:background face won't quite do the trick either. Instead, we dedicate
our basic color expectations in a new FACES attribute: basecolors. I
expect to make use of this new design soon to help implement colour
blending.

For now, the HTML colour codes are put there, along with two special
colors: foreground, and background. These are then used in the default
face, and let us disambiguate usage.
diff --git a/docs/src/internals.md b/docs/src/internals.md
@@ -8,13 +8,12 @@ opening a pull request or issue to discuss making them part of the public API.
 ```@docs
 StyledStrings.ANSI_4BIT_COLORS
 StyledStrings.FACES
-StyledStrings.HTML_BASIC_COLORS
 StyledStrings.Legacy.ANSI_256_COLORS
 StyledStrings.Legacy.NAMED_COLORS
 StyledStrings.Legacy.RENAMED_COLORS
 StyledStrings.Legacy.legacy_color
 StyledStrings.Legacy.load_env_colors!
-StyledStrings.ansi_4bit_color_code
+StyledStrings.ansi_4bit
 StyledStrings.face!
 StyledStrings.getface
 StyledStrings.loadface!
diff --git a/src/faces.jl b/src/faces.jl
@@ -318,8 +318,8 @@ const FACES = let default = Dict{Symbol, Face}(
     :default => Face(
         "monospace", 120,      # font, height
         :normal, :normal,      # weight, slant
-        SimpleColor(:default), # foreground
-        SimpleColor(:default), # background
+        SimpleColor(:foreground), # foreground
+        SimpleColor(:background), # background
         false, false, false,   # underline, strikethrough, overline
         Symbol[]),              # inherit
     # Property faces
@@ -382,7 +382,30 @@ const FACES = let default = Dict{Symbol, Face}(
     :repl_prompt_pkg => Face(inherit=[:blue, :repl_prompt]),
     :repl_prompt_beep => Face(inherit=[:shadow, :repl_prompt]),
     )
-    (; default, current=ScopedValue(copy(default)), lock=ReentrantLock())
+    basecolors = Dict{Symbol, RGBTuple}(
+        :background     => (r = 0xff, g = 0xff, b = 0xff),
+        :foreground     => (r = 0x00, g = 0x00, b = 0x00),
+        :black          => (r = 0x1c, g = 0x1a, b = 0x23),
+        :red            => (r = 0xa5, g = 0x1c, b = 0x2c),
+        :green          => (r = 0x25, g = 0xa2, b = 0x68),
+        :yellow         => (r = 0xe5, g = 0xa5, b = 0x09),
+        :blue           => (r = 0x19, g = 0x5e, b = 0xb3),
+        :magenta        => (r = 0x80, g = 0x3d, b = 0x9b),
+        :cyan           => (r = 0x00, g = 0x97, b = 0xa7),
+        :white          => (r = 0xdd, g = 0xdc, b = 0xd9),
+        :bright_black   => (r = 0x76, g = 0x75, b = 0x7a),
+        :grey           => (r = 0x76, g = 0x75, b = 0x7a),
+        :gray           => (r = 0x76, g = 0x75, b = 0x7a),
+        :bright_red     => (r = 0xed, g = 0x33, b = 0x3b),
+        :bright_green   => (r = 0x33, g = 0xd0, b = 0x79),
+        :bright_yellow  => (r = 0xf6, g = 0xd2, b = 0x2c),
+        :bright_blue    => (r = 0x35, g = 0x83, b = 0xe4),
+        :bright_magenta => (r = 0xbf, g = 0x60, b = 0xca),
+        :bright_cyan    => (r = 0x26, g = 0xc6, b = 0xda),
+        :bright_white   => (r = 0xf6, g = 0xf5, b = 0xf4))
+    (; default, basecolors,
+     current = ScopedValue(copy(default)),
+     lock = ReentrantLock())
 end
 
 ## Adding and resetting faces ##
diff --git a/src/io.jl b/src/io.jl
@@ -30,21 +30,17 @@ const ANSI_4BIT_COLORS = Dict{Symbol, Int}(
     :bright_white => 15)
 
 """
-    ansi_4bit_color_code(color::Symbol, background::Bool=false)
+    ansi_4bit(color::Integer, background::Bool=false)
+
+Provide the color code (30-37, 40-47, 90-97, 100-107) for `color` (0–15).
 
-Provide the color code (30-37, 40-47, 90-97, 100-107) for `color`, as an integer.
 When `background` is set the background variant will be provided, otherwise
 the provided code is for setting the foreground color.
 """
-function ansi_4bit_color_code(color::Symbol, background::Bool=false)
-    code = get(ANSI_4BIT_COLORS, color, nothing)
-    if code !== nothing
-        code >= 8 && (code += 52)
-        background && (code += 10)
-        code + 30
-    else
-        ifelse(background, 49, 39)
-    end
+function ansi_4bit(code::Integer, background::Bool=false)
+    code >= 8 && (code += 52)
+    background && (code += 10)
+    code + 30
 end
 
 """
@@ -96,6 +92,8 @@ 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)
 
@@ -110,31 +108,45 @@ If `color` is a `SimpleColor{Symbol}`, the value should be a a member of
 
 If `color` is a `SimpleColor{RGBTuple}` and `get_have_truecolor()` returns true,
 24-bit color is used. Otherwise, an 8-bit approximation of `color` is used.
+
+If `color` is unknown, no output is produced.
 """
 function termcolor(io::IO, color::SimpleColor, category::Char)
+    if category == '4'
+        if color.value ∈ (:background, FACES.basecolors[:background])
+            return print(io, "\e[", category, "9m")
+        elseif color.value == :foreground
+            return print(io, "\e[47m") # Technically not quite, but close enough
+        end
+    elseif color.value ∈ (:foreground, FACES.basecolors[:foreground])
+        return print(io, "\e[", category, "9m")
+    elseif category == '3' && color.value == :background
+        return print(io, "\e[30m") # Technically not quite, but close enough
+    end
+    for _ in 1:MAX_COLOR_FORWARDS
+        color.value isa RGBTuple && break
+        fg = get(FACES.current[], color.value, Face()).foreground
+        isnothing(fg) && return
+        color == fg && break
+        color = fg
+    end
     if color.value isa RGBTuple
         if Base.get_have_truecolor()
             termcolor24bit(io, color.value, category)
         else
             termcolor8bit(io, color.value, category)
         end
-    elseif color.value === :default
-        print(io, "\e[", category, "9m")
-    elseif (fg = get(FACES.current[], color.value, getface()).foreground) != SimpleColor(color.value)
-        termcolor(io, fg, category)
-    else
-        print(io, "\e[")
-        if category == '3' || category == '4'
-            print(io, ansi_4bit_color_code(color.value, category == '4'))
-        elseif category == '5'
-            if haskey(ANSI_4BIT_COLORS, color.value)
-                print(io, "58;5;", ANSI_4BIT_COLORS[color.value])
-            else
-                print(io, "59")
-            end
-         end
-         print(io, "m")
+        return
+    end
+    ansi = get(ANSI_4BIT_COLORS, color.value, nothing)
+    isnothing(ansi) && return
+    print(io, "\e[")
+    if category == '3' || category == '4'
+        print(io, ansi_4bit(ansi, category == '4'))
+    elseif category == '5'
+        print(io, "58;5;", ansi)
     end
+    print(io, 'm')
 end
 
 """
@@ -208,7 +220,7 @@ function termstyle(io::IO, face::Face, lastface::Face=getface())
                 termcolor(io, face.underline, '5')
             else
                 if lastface.underline isa SimpleColor || lastface.underline isa Tuple && first(lastface.underline) isa SimpleColor
-                    termcolor(io, SimpleColor(:none), '5')
+                    termcolor(io, SimpleColor(:foreground), '5')
                 end
                 print(io, ifelse(face.underline == true,
                                 ANSI_STYLE_CODES.start_underline,
@@ -233,9 +245,10 @@ function _ansi_writer(string_writer::F, io::IO, s::Union{<:AnnotatedString, SubS
     # We need to make sure that the customisations are loaded
     # before we start outputting any styled content.
     load_customisations!()
+    default = FACES.default[:default]
     if get(io, :color, false)::Bool
         buf = IOBuffer() # Avoid the overhead in repeatedly printing to `stdout`
-        lastface::Face = FACES.default[:default]
+        lastface::Face = default
         for (str, styles) in eachregion(s)
             face = getface(styles)
             link = let idx=findfirst(==(:link) ∘ first, styles)
@@ -248,7 +261,7 @@ function _ansi_writer(string_writer::F, io::IO, s::Union{<:AnnotatedString, SubS
             !isnothing(link) && write(buf, "\e]8;;\e\\")
             lastface = face
         end
-        termstyle(buf, FACES.default[:default], lastface)
+        termstyle(buf, default, lastface)
         write(io, seekstart(buf))
     elseif s isa AnnotatedString
         string_writer(io, s.string)
@@ -296,39 +309,24 @@ Base.AnnotatedDisplay.show_annot(io::IO, ::MIME"text/html", s::Union{<:Annotated
 # End AnnotatedDisplay hooks
 # ------------
 
-"""
-A mapping between ANSI named colors and 8-bit colors for use in HTML
-representations.
-"""
-const HTML_BASIC_COLORS = Dict{Symbol, SimpleColor}(
-    :black => SimpleColor(0x1c, 0x1a, 0x23),
-    :red => SimpleColor(0xa5, 0x1c, 0x2c),
-    :green => SimpleColor(0x25, 0xa2, 0x68),
-    :yellow => SimpleColor(0xe5, 0xa5, 0x09),
-    :blue => SimpleColor(0x19, 0x5e, 0xb3),
-    :magenta => SimpleColor(0x80, 0x3d, 0x9b),
-    :cyan => SimpleColor(0x00, 0x97, 0xa7),
-    :white => SimpleColor(0xdd, 0xdc, 0xd9),
-    :bright_black => SimpleColor(0x76, 0x75, 0x7a),
-    :grey => SimpleColor(0x76, 0x75, 0x7a),
-    :gray => SimpleColor(0x76, 0x75, 0x7a),
-    :bright_red => SimpleColor(0xed, 0x33, 0x3b),
-    :bright_green => SimpleColor(0x33, 0xd0, 0x79),
-    :bright_yellow => SimpleColor(0xf6, 0xd2, 0x2c),
-    :bright_blue => SimpleColor(0x35, 0x83, 0xe4),
-    :bright_magenta => SimpleColor(0xbf, 0x60, 0xca),
-    :bright_cyan => SimpleColor(0x26, 0xc6, 0xda),
-    :bright_white => SimpleColor(0xf6, 0xf5, 0xf4))
-
-function htmlcolor(io::IO, color::SimpleColor)
+function htmlcolor(io::IO, color::SimpleColor, background::Bool = false)
+    default = getface()
     if color.value isa Symbol
-        if color.value === :default
+        if background && color.value == :background
+            print(io, "initial")
+        elseif !background && color.value == :foreground
             print(io, "initial")
-        elseif (fg = get(FACES.current[], color.value, getface()).foreground) != SimpleColor(color.value)
+        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
-            htmlcolor(io, get(HTML_BASIC_COLORS, color.value, SimpleColor(:default)))
+            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, '#')
@@ -387,7 +385,7 @@ function cssattrs(io::IO, face::Face, lastface::Face=getface(), escapequotes::Bo
     end
     if background != lastbackground
         printattr(io, "background-color")
-        htmlcolor(io, background)
+        htmlcolor(io, background, true)
     end
     face.underline == lastface.underline ||
         if face.underline isa Tuple # Color and style
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -235,8 +235,8 @@ end
                 height: 120
                 weight: normal
                  slant: normal
-            foreground: default
-            background: default
+            foreground: foreground
+            background: background
              underline: false
          strikethrough: false
                inverse: false\
@@ -248,8 +248,8 @@ end
                 height: 120
                 weight: normal
                  slant: normal
-            foreground: ■ default
-            background: ■ default
+            foreground: ■ foreground
+            background: \e[30m■\e[39m background
              underline: false
          strikethrough: false
                inverse: false\
@@ -475,11 +475,14 @@ end
 
 @testset "ANSI encoding" begin
     # 4-bit color
-    @test StyledStrings.ansi_4bit_color_code(:cyan, false) == 36
-    @test StyledStrings.ansi_4bit_color_code(:cyan, true) == 46
-    @test StyledStrings.ansi_4bit_color_code(:bright_cyan, false) == 96
-    @test StyledStrings.ansi_4bit_color_code(:bright_cyan, true) == 106
-    @test StyledStrings.ansi_4bit_color_code(:nonexistant) == 39
+    @test StyledStrings.ansi_4bit(
+        StyledStrings.ANSI_4BIT_COLORS[:cyan], false) == 36
+    @test StyledStrings.ansi_4bit(
+        StyledStrings.ANSI_4BIT_COLORS[:cyan], true) == 46
+    @test StyledStrings.ansi_4bit(
+        StyledStrings.ANSI_4BIT_COLORS[:bright_cyan], false) == 96
+    @test StyledStrings.ansi_4bit(
+        StyledStrings.ANSI_4BIT_COLORS[:bright_cyan], true) == 106
     # 8-bit color
     @test sprint(StyledStrings.termcolor8bit, (r=0x40, g=0x63, b=0xd8), '3') == "\e[38;5;26m"
     @test sprint(StyledStrings.termcolor8bit, (r=0x38, g=0x98, b=0x26), '3') == "\e[38;5;28m"
@@ -606,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=\"\">terminal</span> and graphical displays."
+        styling</span> system, suitable for <span style=\"color: initial; background-color: #000000\">terminal</span> and graphical displays."
 end
 
 @testset "Legacy" begin
