Kotter Files

This major release brings robust Unicode support to Kotter, plus a slew improvements to the input and grid features. We also spent a lot of time enhancing the Virtual Terminal experience.

 __  __          __    __
/\ \/\ \        /\ \__/\ \__
\ \ \/'/'    ___\ \ ,_\ \ ,_\    __   _ __
 \ \ , <    / __`\ \ \/\ \ \/  /'__`\/\`'__\
  \ \ \\`\ /\ \L\ \ \ \_\ \ \_/\  __/\ \ \/
   \ \_\ \_\ \____/\ \__\\ \__\ \____\\ \_\
    \/_/\/_/\/___/  \/__/ \/__/\/____/ \/_/
               _         __     
             /' \      /'__`\   
            /\_, \    /\_\L\ \  
            \/_/\ \   \/_/_\_<_ 
               \ \ \  __/\ \L\ \
                \ \_\/\_\ \____/
                 \/_/\/_/\/___/

Changes

Unicode

Unicode support has been improved across the board.

• You can now put emojis and other wide characters (e.g. CJK) inside bordered areas and grids, and the widths will be calculated correctly. No more broken borders!

• We now expose a TextMetrics instance in the session scope which provides useful Unicode utility methods.

• For example: textMetrics.renderWidthOf("日本語") // returns 6, not 3

• Please see its README section for more information.

• The text metrics class additionally provides a very useful truncateToWidth method which can help you fit long strings into areas of limited width.

• You can pass in an optional ellipsis value for a softer truncate, e.g. "Hello Wor" vs. "Hello Wo…"
• ... and you can specify if that truncate happens at the end, start, or middle of the string, e.g. "Hel…", "…llo", "He…o"

Input improvements

• Added a new onInputCursorChanged callback which lets you intercept the cursor position navigating around text inputs.
• onInputChanged now includes an edit parameter which contains detailed information about the exact edit that caused it
• This tells you if the text was added, removed by backspace, or removed by delete.
• You can now control the cursor width, allowing you to highlight chunks of text as the user navigates around the input string.
• Please see the added hiragana example to see these new features in action.

Virtual Terminal

• We now support a new twemoji dependency, which, if added to your project, allows the virtual terminal to access a huge collection of "twemoji" SVG emojis, providing a richer, more consistent cross-platform experience for people intentionally using the virtual terminal. 
• Please see the relevant README section for more information.
• Fixed a ton of emoji / unicode issues (for example, emojis now line up with regular text)
• The terminal repainting logic was updated and should feel more performant.
• The scrollbar designs have been updated to something that feels more modern and elegant.
• You can now also optionally pass in a boolean to disable the vscroll bar from ever showing up, which can be useful if you know you won't ever need it and want to remove the tiny amount of space reserved for it.
• We revisited the color values and tweaked them to significantly improve readability.

Grid improvements

• You can now prevent some / all of your grid's horizontal separator lines from rendering.
• This can help you make dense grids that fit into very limited vertical space.
• Common configurations are: All, None, TopAndBottom, and HeaderAndBottom
• We updated the grid example to demonstrate this new feature.
• You can optionally reference a CellMetrics object passed into the cell callback, which for now lets you know the cell's width (potentially useful for "fit" and "star" columns) kotlin grid(...) { cell { cellMetrics -> text(textMetrics.truncateToWidth(longString, metrics.width)) } }
• Grids now default to GridCharacters.BoxThin (used to be Ascii) for a nicer out-of-the-box look.

Misc

• Updated some value names from SCREAMING_SNAKE_CASE to PascalCase, in line with the Kotlin style guide for singleton objects.
• For example, Keys.SPACE is now Keys.Space

• The old names have been deprecated and will be removed in a future release.

• ⚠️ Key matching is now case-insensitive

• So for example: when(key) { Keys.Q -> ... } will match both lower and upper-case Q keypresses.
• Values like UPPER_Q are now deprecated.

• If you really need to distinguish case , use isUpper: when(key) { Keys.Q -> if (key.isUpper() quit() else checkForQuitConfirmation()) }

• Fixed a gnarly timing issue where escape-sequence keys (arrows, function keys, etc.) could occasionally fire a spurious bare ESC keypress.

• Delay auto-appending a newline to a section until it is finished running.

• Kotter always finishes a section with a newline before starting the next, but now we at least wait until the section is finished first. This allows information-dense TUI applications to avoid wasting valuable space on a blank line at the bottom of the window.

Test utils

• You can now set the width of the in-memory test terminal, which will result in wrapped text, similar to a real terminal.

Thanks!

• @239 offered a ton of feedback, support, and validation, raising a lot of excellent issues and making a huge impact on this release. Specifically, he worked on the grid feature and helped drive a lot of the unicode and Virtual Terminal improvements.
• loke who connected with me and described the problem that led to the input fixes in this release.

Full Changelog: https://github.com/varabyte/kotter/compare/v1.2.1...v1.3.0