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

Issue #18996 has been updated by st0012 (Stan Lo).


hsbt (Hiroshi SHIBATA) wrote in #note-10:
> 
> ```ruby
> Reline.completion_colors = {
>   foreground: :white,
>   background: :black,
>   selected_text: :black,
>   selection: :white
> }
> ```


I agree that `color` postfix is a bit redundant. But I still lean *slightly* toward having it because it makes passing values easier:

```rb
DialogRenderInfo.new(
  pos: Reline::CursorPos.new(x, y), 
  contents: contents, 
  width: width, 
  **Reline.completion_colors
)
```

And when doing so, users get errors when they have typos or unsupported attributes in their `Reline.completion_colors`, for example.

But I'll take either one decided in the dev meeting.

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

* 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.


---Files--------------------------------
Screenshot 2022-10-18 at 15.25.36.png (9.7 KB)


-- 
https://bugs.ruby-lang.org/
 ______________________________________________
 ruby-core mailing list -- [e-mail]
 To unsubscribe send an email to [e-mail]
 ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/