feat(backend): add window size api

[benjajaja]

Depends on crossterm-rs/crossterm#790, and should update crossterm in an independent PR. Related to #215

For image (sixel, iTerm2, Kitty...) support that handles graphics in
terms of Rect so that the image area can be included in layouts.

For example: an image is loaded with a known pixel-size, and drawn, but
the image protocol has no mechanism of knowing the actual cell/character
area that been drawn on. It is then impossible to skip overdrawing the
area.

Returning the window size in pixel-width / pixel-height, together with
colums / rows, it can be possible to account the pixel size of each cell
/ character, and then known the Rect of a given image, and also resize
the image so that it fits exactly in a Rect and avoid artifacts.

[codecov]

Codecov Report

Merging #276 (dbf0c5c) into main (ad3413e) will increase coverage by 0.36%.
Report is 6 commits behind head on main.
The diff coverage is 31.32%.

❗ Current head dbf0c5c differs from pull request most recent head 09589b7. Consider uploading reports for the commit 09589b7 to get more accurate results

@@            Coverage Diff             @@
##             main     #276      +/-   ##
==========================================
+ Coverage   89.25%   89.61%   +0.36%     
==========================================
  Files          40       40              
  Lines       10767    10939     +172     
==========================================
+ Hits         9610     9803     +193     
+ Misses       1157     1136      -21     

Files Changed	Coverage Δ
src/backend/crossterm.rs	0.00% <0.00%> (ø)
src/backend/mod.rs	82.92% <ø> (ø)
src/backend/termion.rs	26.36% <0.00%> (-1.10%)	⬇️
src/backend/termwiz.rs	0.00% <0.00%> (ø)
src/backend/test.rs	95.25% <0.00%> (+52.01%)	⬆️
src/terminal.rs	58.30% <80.00%> (ø)
src/layout.rs	98.12% <85.71%> (-0.27%)	⬇️

... and 1 file with indirect coverage changes

[joshka]

Rewrite the commit message title in the convention commit style using imperative tone (e.g. feat(backend): add window_size_in_pixels() method).

This is pretty close to being mergable (or will be once the crossterm PR is merged), so can you please rebase and squash your commits into a single commit and setup commit signing? See https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits for info.

[joshka]

Backend is woefully under-tested. I wonder if there's some way to fix that.

[benjajaja]

Regarding tests, I don't think it's really feasible to cover this. window_size() really depends on being run as a graphical application, i.e. xorg, wayland, maybe even fbdev, but AFAIK near impossible in docker / github runners.

[joshka]

I think there was a mention of this not yet working with windows on crossterm if I read the linked issue right. Can you make sure to document this in the crossterm docs for the window_size method?

[joshka]

BTW, another PR upgraded crossterm 0.27 and brought in the changes to the error bits. Can you rebase this on main please?

[benjajaja]

I tried adding some test coverage for insert_before, but that did require to implement clear_region() and append_line() for TestBackend for which I don't know exactly how to implement the different "clear types", e.g. AfterCursor etc. In general, it seemed a bit pointless to test insert_before against TestBackend.

[joshka]

I think perhaps make this non-breaking with the existing size() and resize() continuing to take Rects? We can come back to that decision at a later date however.

Aiming for a 0.23.0 release after the weekend, so this should be in that if you can make the changes in time.

[benjajaja]

@joshka I toned this down to only adding the new window_resize() method, still introducing the new Size struct but not using it in src/terminal.rs so no breaking changes. Also dropped the truncation in Size copied from Rect, as its main purpose is to keep area (and maybe indirectly Buffer::content) in bounds, and there are no more conversions between Size and Rect now.

It's cool if we can get this into the release, but it's not critical like the cell skipping, as the window pixel size can be queried outside of ratatui.

---

Some thoughts on Size vs Rect in Terminal:

In Terminal, there is a last_known_size that may have non-zero x,y if the viewport is Viewport::Fixed(Rect). However it seems like the field is used exclusively by Viewport::Inline(u16).

In general, I think it could be healthy to cut down a few public methods in Terminal: autoresize, resize, size (is just a wrapper to backend.size()), and area of CompletedFrame returned by draw.

[joshka]

This looks good now. Thanks again. This seems like something we could merge before release. I'll flip it to the other maintainers to take a look.

Comments are non-blocking

[mindoodoo]

Looks good ! Thanks for this !

I'll have to take a look at the image crate soon ! Exciting stuff.

@joshka what do you think about the scope of the conventional commit PR title ? let me know if anything else would be more suited. Thanks for all the review on this !

[joshka]

@joshka what do you think about the scope of the conventional commit PR title ? let me know if anything else would be more suited. Thanks for all the review on this !

I think it's probably ok as is. Merging this now. Thanks again @benjajaja. This is going to lead to some fun apps.