[docs] mention semantic() color

tstack · tstack · commit 63128cfe4693 · 2026-04-29T13:35:15.000-07:00
Related to #1653
diff --git a/docs/schemas/config-v1.schema.json b/docs/schemas/config-v1.schema.json
@@ -1400,17 +1400,18 @@
                 },
                 "color": {
                     "title": "/color",
-                    "description": "The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.",
+                    "description": "The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.",
                     "type": "string",
                     "examples": [
                         "#fff",
                         "Green",
-                        "$black"
+                        "$black",
+                        "semantic()"
                     ]
                 },
                 "background-color": {
                     "title": "/background-color",
-                    "description": "The background color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.",
+                    "description": "The background color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.",
                     "type": "string",
                     "examples": [
                         "#2d2a2e",
diff --git a/docs/schemas/format-v1.schema.json b/docs/schemas/format-v1.schema.json
@@ -965,17 +965,18 @@
                 },
                 "color": {
                     "title": "/color",
-                    "description": "The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.",
+                    "description": "The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.",
                     "type": "string",
                     "examples": [
                         "#fff",
                         "Green",
-                        "$black"
+                        "$black",
+                        "semantic()"
                     ]
                 },
                 "background-color": {
                     "title": "/background-color",
-                    "description": "The background color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.",
+                    "description": "The background color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.",
                     "type": "string",
                     "examples": [
                         "#2d2a2e",
diff --git a/docs/source/config.rst b/docs/source/config.rst
@@ -143,6 +143,9 @@ the values from the :code:`styles/text` definition.
   picked based on the `CIEDE2000 <https://en.wikipedia.org/wiki/Color_difference#CIEDE2000>`_
   color difference algorithm.
 
+The special value :code:`semantic()` can also be used in place of a color.
+The displayed color is derived from a hash of the text to create a stable,
+distinguishable color.
 
 
 Example
diff --git a/src/styling.cc b/src/styling.cc
@@ -72,21 +72,24 @@ const json_path_container style_config_handlers =
         .with_description("How to align text within a cell")
         .for_field(&style_config::sc_text_align),
         yajlpp::property_handler("color")
-            .with_synopsis("#hex|color_name")
+            .with_synopsis("#hex|color_name|semantic()")
             .with_description(
                 "The foreground color value for this style. The value can be "
-                "the name of an xterm color, the hexadecimal value, or a theme "
-                "variable reference.")
+                "the name of an xterm color, the hexadecimal value, a theme "
+                "variable reference, or 'semantic()' to derive the color from "
+                "a hash of the matched text.")
             .with_example("#fff"_frag)
             .with_example("Green"_frag)
             .with_example("$black"_frag)
+            .with_example("semantic()"_frag)
             .for_field(&style_config::sc_color),
         yajlpp::property_handler("background-color")
-            .with_synopsis("#hex|color_name")
+            .with_synopsis("#hex|color_name|semantic()")
             .with_description(
                 "The background color value for this style. The value can be "
-                "the name of an xterm color, the hexadecimal value, or a theme "
-                "variable reference.")
+                "the name of an xterm color, the hexadecimal value, a theme "
+                "variable reference, or 'semantic()' to derive the color from "
+                "a hash of the matched text.")
             .with_example("#2d2a2e"_frag)
             .with_example("Green"_frag)
             .for_field(&style_config::sc_background_color),
diff --git a/test/expected/test_config.sh_a0907769aba112d628e7ebe39c4ec252e5e0bc69.err b/test/expected/test_config.sh_a0907769aba112d628e7ebe39c4ec252e5e0bc69.err
@@ -3,8 +3,8 @@
 [36m | [0m[37m[40m                        "bad-property": "abc"[0m
 [36m =[0m   [36mhelp[0m: [1mAvailable Properties[0m
            [1mtext-align[0m [4mstart|center|end[0m
-           [1mcolor[0m [4m#hex|color_name[0m
-           [1mbackground-color[0m [4m#hex|color_name[0m
+           [1mcolor[0m [4m#hex|color_name|semantic()[0m
+           [1mbackground-color[0m [4m#hex|color_name|semantic()[0m
            [1munderline[0m 
            [1mbold[0m 
            [1mitalic[0m 
@@ -78,13 +78,14 @@
 [1m[31m |      [0m  [1m[31mreason[0m: Unknown color: 'InvalidColor'.  See https://jonasjacek.github.io/colors/ for a list of supported color names
 [36m --> [0m[1m{test_dir}/bad-config2/configs/invalid-theme/config.json[0m:8
 [36m =[0m [36mhelp[0m: [1mProperty Synopsis[0m
-           [1m/ui/theme-defs/invalid-theme/styles/text/color[0m [4m#hex|color_name[0m
+           [1m/ui/theme-defs/invalid-theme/styles/text/color[0m [4m#hex|color_name|semantic()[0m
          [1mDescription[0m
-           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.
+           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.
          [1mExamples[0m
            #fff
            Green
            $black
+           semantic()
 [1m[31m✘[0m [1m[31merror[0m: invalid value for property “[1m/ui/theme[0m”
  [1m[31mreason[0m: unknown theme -- “foo”
 [1m[31m |      [0m [36m =[0m [36mhelp[0m: The available themes are: default, dracula, eldar, grayscale, invalid-theme, modus-operandi, monocai, night-owl, solarized-dark, solarized-light
diff --git a/test/expected/test_config.sh_d622658dc98327b1b2fd346802d24bc633e34ac7.err b/test/expected/test_config.sh_d622658dc98327b1b2fd346802d24bc633e34ac7.err
@@ -3,10 +3,11 @@
 [1m[31m |      [0m  [1m[31mreason[0m: Could not parse color: #f
 [36m --> [0m[1mcommand-option[0m:1
 [36m =[0m [36mhelp[0m: [1mProperty Synopsis[0m
-           [1m/ui/theme-defs/default/styles/text/color[0m [4m#hex|color_name[0m
+           [1m/ui/theme-defs/default/styles/text/color[0m [4m#hex|color_name|semantic()[0m
          [1mDescription[0m
-           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.
+           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.
          [1mExamples[0m
            #fff
            Green
            $black
+           semantic()

-Original file line number
+Diff line change
 [36m | [0m[37m[40m                        "bad-property": "abc"[0m
 [36m =[0m   [36mhelp[0m: [1mAvailable Properties[0m
            [1mtext-align[0m [4mstart|center|end[0m
 -           [1mcolor[0m [4m#hex|color_name[0m
 -           [1mbackground-color[0m [4m#hex|color_name[0m
 +           [1mcolor[0m [4m#hex|color_name|semantic()[0m
 +           [1mbackground-color[0m [4m#hex|color_name|semantic()[0m
            [1munderline[0m
            [1mbold[0m
            [1mitalic[0m
 [1m[31m |      [0m  [1m[31mreason[0m: Unknown color: 'InvalidColor'.  See https://jonasjacek.github.io/colors/ for a list of supported color names
 [36m --> [0m[1m{test_dir}/bad-config2/configs/invalid-theme/config.json[0m:8
 [36m =[0m [36mhelp[0m: [1mProperty Synopsis[0m
 -           [1m/ui/theme-defs/invalid-theme/styles/text/color[0m [4m#hex|color_name[0m
 +           [1m/ui/theme-defs/invalid-theme/styles/text/color[0m [4m#hex|color_name|semantic()[0m
          [1mDescription[0m
 -           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.
 +           The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, a theme variable reference, or 'semantic()' to derive the color from a hash of the matched text.
          [1mExamples[0m
            #fff
            Green
            $black
 +           semantic()
 [1m[31m✘[0m [1m[31merror[0m: invalid value for property “[1m/ui/theme[0m”
  [1m[31mreason[0m: unknown theme -- “foo”
 [1m[31m |      [0m [36m =[0m [36mhelp[0m: The available themes are: default, dracula, eldar, grayscale, invalid-theme, modus-operandi, monocai, night-owl, solarized-dark, solarized-light