[ruby-core:110192] [Ruby master Feature#18996] Proposal: Introduce new APIs to reline for changing dialog UI colours

["k0kubun (Takashi Kokubun)" <noreply@ruby-lang.org>]

Issue #18996 has been updated by k0kubun (Takashi Kokubun).


### Naming Convention
Looking at #note-3, the last dev-meeting's primary ask was to provide a rationale for naming the configurations. So far, the following things have been mentioned:

* [ECMA-48 standard](https://www.ecma-international.org/wp-content/uploads/ECMA-48_5th_edition_june_1991.pdf)
* [ANSI escape code - Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code)
* [Console Virtual Terminal Sequences - Windows Terminal](https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences#text-formatting)
* Terminal.app

It seems like #note-4 discussed individual configurations with different reasoning, however, because the concern is about additional future settings, we should choose a consistent way to name them if possible.

My two cents: Given that these configurations are tightly coupled with terminal applications, I think it should be consistent with the names used in terminal applications, at least for concepts that exist in terminal apps, e.g. `foreground`, `background`. For concepts that don't exist in terminal apps, we could use what Reline names, e.g. `dialog`, or carefully pick an arbitrary name that makes the most sense as a last resort.

### Completion vs Documentation
[Feature #19010] suggested the possibility that, if we were to introduce a color theme to IRB, we'd like to configure colors of other things such as syntax highlight as well. When a color theme can specify different colors for different components, we might want to use different colors for completion and documentation in the future.

If completion and documentation are implemented differently by `SHOW_DOC_DIALOG` and `DEFAULT_DIALOG_PROC_AUTOCOMPLETE`, why don't you just separate color configs for those two things? If you introduce only a color config for auto-completion, which is the actual scope of the problem discussed in this ticket in the first place, for the place of `highlighted`, you'll be able to comfortably use a name that is consistent with terminal apps, `selection`.

----------------------------------------
Feature #18996: Proposal: Introduce new APIs to reline for changing dialog UI colours
https://bugs.ruby-lang.org/issues/18996#change-99467

* Author: st0012 (Stan Lo)
* Status: Open
* Priority: Normal
----------------------------------------
### TL;DR

I want to add APIs to `reline` for changing its dialog item's colors.
The APIs I want to add actually have been merged but becaue:

1. This is a design change
2. The maintainer @aycabta is not available to approve nor reject them

I want to raise it here to decide if we should:

1. Drop them
2. Modify them
3. Officiallty accept them

### Background

After version `1.4`, `irb` provides autocompletion support, which is a great feature and has increased many developers' productivity significantly.
But there's an user-experience issue: the completion items' UI colors (set in `reline`) [are not configurable](https://github.com/ruby/reline/blob/9ab5850444b49aff8e360a84eb1dfa425e96ced1/lib/reline/line_editor.rb#L744-L749). So depending on the user's terminal theme, some may find it hard to use because the background and the text having low-contrast colors, like this:

![](https://user-images.githubusercontent.com/3303032/148653612-e3dff786-1a10-4923-a0eb-3975cae10a7f.png)

And if that happens, the user has no way to fix it. This caused users to open issues like:

- https://github.com/ruby/irb/issues/351
- https://github.com/ruby/irb/issues/328

for being able to change it.

Some users even decided to disable it completely because the colors are unreadable to them. I have also seen people sharingtips for disabling this feature: [example](https://twitter.com/sdogruyol/status/1538512030449254400). So I believe it may be bothering many developers.

Personally I really like this feature but the background also bothers me:

![Screenshot 2022-09-07 at 22 55 12](https://user-images.githubusercontent.com/5079556/188990620-5ec7ba0c-97ab-48d6-a51f-fd16315e3631.png)

And that's why I want to improve it by making the colors configurable and potentially also by providing simple light/dark themes from `irb`.

### Proposal

For the dialog UI, there are 2 element states: `highlighted` and `default`. In `irb`'s case, the selected completion candidate will be `highlighted`, and the rest of options will be `default`. And each state has 2 colors: `foreground (text)` and `background (block)`.

This means the `reline` should allow `irb` and/or users to configure:

- Default items' foreground color
- Default items' background color
- Highlighted items' foreground color
- Highlighted items' background color

That brings us to these APIs:

- `Reline.dialog_default_fg_color`
- `Reline.dialog_default_bg_color`
- `Reline.dialog_highlight_fg_color`
- `Reline.dialog_highlight_bg_color`

And because `reline` only supports coloring through ANSI sequences, these APIs only has 8 available colors if we exclude their bright variants:

- Black
- Red
- Green
- Yellow
- Blue
- Magenta
- Cyan
- White

Given the limited options and also to prevent users from entering non-color ANSI sequences, these APIs only take color names directly:

- :black
- :red
- :green
- :yellow
- :blue
- :magenta
- :cyan
- :white

Example:

```rb
Reline.dialog_default_bg_color = :black
puts Reline.dialog_default_bg_color_sequence #=> 40
Reline.dialog_default_fg_color = :white
puts Reline.dialog_default_fg_color_sequence #=> 37
Reline.dialog_highlight_bg_color = :blue
puts Reline.dialog_highlight_bg_color_sequence #=> 34
Reline.dialog_highlight_fg_color = :black
puts Reline.dialog_highlight_fg_color_sequence #=> 30
```

I have made a [proof of concept PR](https://github.com/ruby/irb/pull/380) on `irb` to show what these APIs can achieve if they or similar ones are adopted.

#### Related PRs

The related changes are made through multiple PRs:

- [Initial APIs PR by @pocari](https://github.com/ruby/reline/pull/413)
- [PR to improve the APIs and make them safer to use](https://github.com/ruby/reline/pull/454)
- [PR to rename the APIs](https://github.com/ruby/reline/pull/456)

#### Other Thoughts

This is more of a concern on the `irb` part, but to make the UI looks comfortable, I think it's better to follow these conditions:

1. An item's foreground and background colors should have high contrast with each other so the texts (foreground) are readable.
2. For the `highlighted` item, its background color should be easily distinguishable from the rest of `default` items.
3. When using dark terminal themes, the `default` items' background is better to be dark as well.




-- 
https://bugs.ruby-lang.org/