feat: add IME cursor positioning support (#2)

[iblea]

There is a bug in pull request #803, so I redesigned and developed a new solution related to the terminal cursor. (Some of the source code from #803 was referenced.)

Problem

The terminal cursor is actually located at the bottom. For languages such as Korean, Japanese, and Chinese, characters must be combined to form complete characters or words. Until the character or word is completed, this is managed by the IME candidate windows buffer and output there. The problem is that because the terminal cursor exists at the bottom, the IME Candidate Windows buffer is also being output at the bottom.

Purpose

When inputting text in {input}, synchronize the terminal cursor to position the "IME candidate windows" at the actual input location.

There may be developers or users who do not need this logic. (English-speaking users, etc.) Therefore, the logic below is implemented to operate only when the enableImeCursor option in the render function is set to true. Even if terminalCursorFocus and terminalCursorPosition props are used, they will not work unless the enableImeCursor option is set to true.

Changes

• Added a terminalCursorFocus prop to the text component.
  • This prop is used to determine which text component should have the terminal cursor focus.
• Added a terminalCursorPosition prop to the text component.
  • This is for efficient cursor control when arrow key input is received.

The location of the example that applies this logic is examples/multi-input/multi-input.tsx.

Below is an example of how to use the terminal cursor in example/chat/chat.tsx.

--- a/examples/chat/chat.tsx
+++ b/examples/chat/chat.tsx
@@ -41,10 +41,12 @@ function ChatApp() {
                        </Box>

                        <Box marginTop={1}>
-                               <Text>Enter your message: {input}</Text>
+                               <Text terminalCursorFocus>Enter your message: {input}</Text>
                        </Box>
                </Box>
        );
 }

-render(<ChatApp />);
+render(<ChatApp />, {
+       enableImeCursor: true,
+});

You can specify which Text component receives terminal focus by setting terminalCursorFocus.

How to test?

npm install
npm run build
# CJK Input Test Example
NODE_NO_WARNINGS=1 node --loader ts-node/esm examples/multi-input/index.ts

Install Korean IME ("two-set keyboard"). and input this. d k s s u d g k t p d y . -> print "안녕하세요."

Install Japanese IME ("Romaji"). and input this. k o n n n i c h i w a。 -> print "こんにちわ。"

Test Checklist

• IME candidate window is properly positioned.
• IME candidate window is properly positioned during multi line (newline) operations.
• The cursor moves correctly when arrow key, home, end, and other key events are input.
• Terminal cursor is properly positioned when the screen overflows (when scrolling occurs).
• The cursor is properly positioned when the terminal size changes.

mp4 test

https://github.com/user-attachments/assets/3270e0e6-8772-4ccb-a776-521f3c808259

I partially developed and verified using Claude Code.