Merge branch 'min-contrast-ratio' of https://github.com/arne314/kitty

kitty/options/definition.py

@@ -265,21 +265,31 @@ Then adjust the second parameter until it looks good. Then switch to a light the
 and adjust the first parameter until the perceived thickness matches the dark theme.
 ''')
 
-opt('text_fg_override_threshold', 0, option_type='float', long_text='''
-The minimum accepted difference in luminance between the foreground and background
-color, below which kitty will override the foreground color. It is percentage
-ranging from :code:`0` to :code:`100`. If the difference in luminance of the
-foreground and background is below this threshold, the foreground color will be set
-to white if the background is dark or black if the background is light. The default
-value is :code:`0`, which means no overriding is performed. Useful when working with applications
+opt('text_fg_override_threshold', '0 %', option_type='text_fg_override_threshold', long_text='''
+A setting to prevent low contrast scenarios, configurable in two different modes (suffix :code:` %` and suffix :code:` ratio`).
+The default value is :code:`0`, which means no overriding is performed. Useful when working with applications
 that use colors that do not contrast well with your preferred color scheme.
 
+A value with the suffix :code:` %` represents the minimum accepted difference in luminance between the foreground and background
+color, below which kitty will override the foreground color. It is percentage
+ranging from :code:`0 %` to :code:`100 %`. If the difference in luminance of the
+foreground and background is below this threshold, the foreground color will be set
+to white if the background is dark or black if the background is light. 
+
+A value with the suffix :code:` ratio` represents the minimum accepted contrast ratio between the foreground and background color.
+Possible values range from :code:`0.0 ratio` to :code:`21.0 ratio`.
+To for example meet :link:`WCAG level AA <https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines>`
+a value of :code:`4.5 ratio` can be provided.
+The algorithm is implemented using :link:`HSLuv <https://www.hsluv.org/>` which enables it to change
+the perceived lightness of a color just as much as needed without really changing its hue and saturation.
+
 WARNING: Some programs use characters (such as block characters) for graphics
 display and may expect to be able to set the foreground and background to the
 same color (or similar colors).  If you see unexpected stripes, dots, lines,
 incorrect color, no color where you expect color, or any kind of graphic
 display problem try setting :opt:`text_fg_override_threshold` to :code:`0` to
-see if this is the cause of the problem.
+see if this is the cause of the problem or consider the minimum contrast ratio (negative value)
+over the minimum difference as it implements a basic workaround for this scenario.
 ''')
 
 egr()  # }}}

kitty/options/parse.py

@@ -19,10 +19,10 @@ from kitty.options.utils import (
     pointer_shape_when_dragging, remote_control_password, resize_debounce_time, scrollback_lines,
     scrollback_pager_history_size, shell_integration, store_multiple, symbol_map, tab_activity_symbol,
     tab_bar_edge, tab_bar_margin_height, tab_bar_min_tabs, tab_fade, tab_font_style, tab_separator,
-    tab_title_template, titlebar_color, to_cursor_shape, to_cursor_unfocused_shape, to_font_size,
-    to_layout_names, to_modifiers, transparent_background_colors, underline_exclusion, url_prefixes,
-    url_style, visual_bell_duration, visual_window_select_characters, window_border_width,
-    window_logo_scale, window_size
+    tab_title_template, text_fg_override_threshold, titlebar_color, to_cursor_shape,
+    to_cursor_unfocused_shape, to_font_size, to_layout_names, to_modifiers,
+    transparent_background_colors, underline_exclusion, url_prefixes, url_style, visual_bell_duration,
+    visual_window_select_characters, window_border_width, window_logo_scale, window_size
 )
 
 
@@ -1327,7 +1327,7 @@ class Parser:
         ans['text_composition_strategy'] = str(val)
 
     def text_fg_override_threshold(self, val: str, ans: dict[str, typing.Any]) -> None:
-        ans['text_fg_override_threshold'] = float(val)
+        ans['text_fg_override_threshold'] = text_fg_override_threshold(val)
 
     def touch_scroll_multiplier(self, val: str, ans: dict[str, typing.Any]) -> None:
         ans['touch_scroll_multiplier'] = float(val)

kitty/options/types.py

@@ -614,7 +614,7 @@ class Options:
     term: str = 'xterm-kitty'
     terminfo_type: choices_for_terminfo_type = 'path'
     text_composition_strategy: str = 'platform'
-    text_fg_override_threshold: float = 0.0
+    text_fg_override_threshold: tuple[float, str] = (0.0, '%')
     touch_scroll_multiplier: float = 1.0
     transparent_background_colors: tuple[tuple[kitty.fast_data_types.Color, float], ...] = ()
     undercurl_style: choices_for_undercurl_style = 'thin-sparse'

kitty/options/utils.py

@@ -26,6 +26,7 @@ from kitty.conf.utils import (
     KeyAction,
     KeyFuncWrapper,
     currently_parsing,
+    number_with_unit,
     percent,
     positive_float,
     positive_int,
@@ -752,6 +753,13 @@ def active_tab_title_template(x: str) -> str | None:
     return None if x == 'none' else x
 
 
+def text_fg_override_threshold(x: str) -> tuple[float, str]:
+    value, unit = number_with_unit(x, default_unit='%')
+    if unit not in ['%', 'ratio']:
+        raise ValueError(f'The unit {unit} is not a valid choice for text_fg_override_threshold')
+    return value, unit
+
+
 ClearOn = Literal['next', 'focus']
 default_clear_on: tuple[ClearOn, ...] = 'focus', 'next'
 all_clear_on = get_args(ClearOn)